Copyright =C2=A9 2018 Packt Publishing

All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, without the prior written permission of the publisher, except in the case of brief quotations embedded in critical articles or reviews.

Every effort has been made in the preparation of this book to ensure the accuracy of the information presented. However, the information contained in this book is sold without warranty, either express or implied. Neither the author(s), nor Packt Publishing or its dealers and distributors, will be held liable for any damages caused or alleged to have been caused directly or indirectly by this book.

Packt Publishing has endeavored to provide trademark information about all of the companies and products mentioned in this book by the appropriate use of capitals. However, Packt Publishing cannot guarantee the accuracy of this information.

Commissioning Editor: Aaron Lazar
Acquisition Editor: Alok Dhuri
Content Development Editor: Zeeyan Pinheiro
Technical Editor: Gaurav Gala
Copy Editor: Safis Editing
Project Coordinator: Vaidehi Sawant
Proofreader: Safis Editing
Indexer: Tejal Daruwale Soni
Graphics: Alishon Mendonsa
Production Coordinator: Nilesh Mohite

First published: September 2018

Production reference: 1280918

Published by Packt Publishing Ltd.
Livery Place
35 Livery Street
Birmingham
B3 2PB, UK.

ISBN 978-1-78839-764-3

www.packtpub.com

 

Mapt is an online digital library that gives you full access to over 5,000 books and videos, as well as industry leading tools to help you plan your personal development and advance your career. For more information, please visit our website.

• Spend less time learning and more time coding with practical eBooks and videos from over 4,000 industry professionals

• Improve your learning with Skill Plans built especially for you

• Get a free eBook or video every month

• Mapt is fully searchable

• Copy and paste, print, and bookmark content

Did you know that Packt offers eBook versions of every book published, with PDF and ePub files available? You can upgrade to the eBook version at www.packt.com and as a print book customer, you are entitled to a discount on the eBook copy. Get in touch with us at customercare@packtpub.com for more details.

At www.packt.com, you can also read a collection of free technical articles, sign up for a range of free newsletters, and receive exclusive discounts and offers on Packt books and eBooks. 

Mika=C3=ABl Valot is Principal Software Engineer at IHS Markit in London, UK. He is the lead developer of a strategic market risk solution for banking regulation.

He has over 15 years of experience in the financial industry of the UK, Switzerland, and France. He has a Dipl=C3=B4me d'Ing=C3=A9nieur in Computing (equivalent to an M.Sc.) from Telecom Nancy, France.

After years of working with Java, he started developing professionally with Scala in 2010, and never looked back. He was a speaker at Scala Exchange 2015.

When he is not coding in Scala, Mika=C3=ABl likes to dabble with Haskell, the Robotic Operating System, and deep learning.

He strongly believes that functional programming with strong typing is the best way to write safe and scalable programs.

Nicolas Jorand is a senior developer. He worked for the finance industry for about 15 years before switching to the energy industry. He is a freelancer enjoying a partial time at Romande Energy, a Swiss utility company providing exclusively green electricity. Nicolas is a full-stack developer, playing with microcontrollers, developing standard web user and 3D interfaces on Unity, developing software to animate a humanoid robot (Nao) and finally, working with Scala on integration and backend software. All these projects are done with the same leitmotif; "In the dev process, get the issues as early as possible."

Vlad Patryshev is currently working as a Lead Data Engineer at Salesforce; he is also a professor of Logic at Santa Clara University.

He is an organizer of two meetups, Bay Area Categories and Types, and Scala Bay, the latter dedicated to Scala language.

Vlad's education is in math, but he spent most of his life working in software. 7 years at Borland, 3.5 years at Google.

If you're interested in becoming an author for Packt, please visit authors.packtpub.com and apply today. We have worked with thousands of developers and tech professionals, just like you, to help them share their insight with the global tech community. You can make a general application, apply for a specific hot topic that we are recruiting an author for, or submit your own idea.

Scala is a type-safe JVM language that incorporates object-oriented programming (OOP) and functional programming (FP) aspects. This book gets you started with the essentials of software development by guiding you through the different aspects of Scala programming, helping you bridge the gap between learning and implementing. You will learn about the unique features of Scala through diverse applications and encounter simple yet powerful approaches for software development. You will see how to use the basic tools, set up the environment, and write Scala programs.

Scala Programming Projects will help you build a number of applications, beginning with a simple project, such as a financial independence calculator, and advancing to other projects, such as a shopping application or a Bitcoin transaction analyzer. You will be able to use various Scala features, such as its OOP and FP capabilities, and learn ways to write concise, reactive, and concurrent applications in a type-safe manner. You will also learn how to use top-notch libraries, such as Akka and Play, and integrate Scala applications with Kafka, Spark, and Zeppelin; plus, you'll explore deploying applications on cloud platforms.

By the end of the book, you will be empowered by knowing the ins and outs of Scala, being able to apply Scala to solve a variety of real-world problems.

If you are an amateur programmer who wishes to learn how to use Scala, this book is for you. Knowledge of Java would be beneficial for, but is not necessary to, understanding the concepts covered in this book.

Chapter 1, Writing Your First Program, explains how to set up your environment to start programming in Scala, covering the basic tools that are required and what the simplest Scala application might look like.

Chapter 2, Developing a Retirement Calculator, puts into practice the features of the Scala language seen in the first chapter. We will also introduce other elements of the Scala language and SDK to develop the model and logic for a retirement calculator. This calculator will help people work out how long they'll need to save and how much they'll need to save to have a comfortable retirement.

Chapter 3, Handling Errors, has you continuing to work on the retirement calculator from the previous chapter, handling the errors that riddle it. For instance, the calculator works correctly as long as the right arguments are passed to it but fails badly with a horrible stack trace if any of the parameters are wrong.

Chapter 4, Advanced Features, explores the more advanced features of Scala. As with any programming language, some advanced constructs might be seldom used in practice or can obfuscate code. We will aim to only explain features that we have encountered in real projects that have been deployed to production.

Chapter 5, Type Classes, you will learn what a type class is, what are the most common type classes in the cats library, and how to use them in your projects.

Chapter 6, Online Shopping =E2=80=93 Persistence, explains how to persist data in a relational database. The data will be the contents of a cart for a shopping website.

Chapter 7, Online Shopping =E2=80=93 REST API, covers how to develop a REST API using Play Framework. API is an acronym for Application Programming Interface, and the acronym REST stands for Representational State Transfer. Basically, we will provide an interface for our application, so that other programs can interact with it.

Chapter 8, Online Shopping =E2=80=93 User Interface, gets you using Scala.js to build the user interface for the online shopping application. In this interface, you will be able to select a product to add to your cart, update the number of products that you wish to buy, and remove them from the cart if needed.

Chapter 9, Interactive Browser, introduces the actor model by extending our shopping project. The extension will consist of a notification, provided to anyone connected to the website, about who is adding/removing a product to/from the cart.

Chapter 10, Fetching and Persisting Bitcoin Market Data, look at developing a data pipeline to fetch, store, and analyze Bitcoin transaction data. We will use Apache Spark in batch mode to do so.

Chapter 11, Batch and Streaming Analytics, focuses on how to use Zeppelin and Spark to query our historical data store. We will use Zeppelin's capability to plot interesting graphs and Apache Kafka with Spark streaming to analyze live transactions.

Basic knowledge of any programming language would be helpful to you during the course of this book. Additional knowledge of Java would also be useful for understanding some concepts covered in this book. There are several levels of involvement to make the most of this book, from the quickest to the most effective:

• You can just read it and look at the code in your IDE.
• While you read it, you can copy and paste the code samples in your IDE and run them.
• Same as before, but this time you re-type all the code samples. Using the auto-completion will make you discover more functions of the API. Typing the code will also make you remember it more. You make use of your visual and kinesthetic memory.
• The Benjamin Franklin method. You read a whole chapter or a section in one go, then close the book. After that, try to re-write the code samples from memory. If you are stuck you can reopen the book. This will force your brain to have a complete picture of a project. You will memorize and understand the concepts in much more depth.
  

You can download the example code files for this book from your account at www.packt.com. If you purchased this book elsewhere, you can visit www.packt.com/support and register to have the files emailed directly to you.

You can download the code files by following these steps:

1. Log in or register at www.packt.com.
2. Select the SUPPORT tab.
3. Click on Code Downloads & Errata.
4. Enter the name of the book in the Search box and follow the onscreen instructions.

Once the file is downloaded, please make sure that you unzip or extract the folder using the latest version of:

• WinRAR/7-Zip for Windows
• Zipeg/iZip/UnRarX for Mac
• 7-Zip/PeaZip for Linux

The code bundle for the book is also hosted on GitHub at https://github.com/PacktPublishing/Scala-Programming-Projects. In case there is an update to the code, it will be updated on the existing GitHub repository.

We also have other code bundles from our rich catalog of books and videos available at https://github.com/PacktPublishing/. Check them out!

We also provide a PDF file that has color images of the screenshots/diagrams used in this book. You can download it here: https://www.packtpub.com/sites/default/files/downloads/9781788397643_ColorImages.pdf.

There are a number of text conventions used throughout this book.

CodeInText: Indicates code words in text, database table names, folder names, filenames, file extensions, pathnames, dummy URLs, user input, and Twitter handles. Here is an example: "Mount the downloaded WebStorm-10*.dmg disk image file as another disk in your system."

A block of code is set as follows:

class LazyDemo {
  lazy val lazyVal = {
    println("Evaluating lazyVal")

When we wish to draw your attention to a particular part of a code block, the relevant lines or items are set in bold:

def lazyEvenPlusOne(xs: Vector[Int]): Vector[Int] =
  xs.withFilter { x => println(s"filter $x"); x % 2 == 0 }

Any command-line input or output is written as follows:

$ mkdir css
$ cd css

Bold: Indicates a new term, an important word, or words that you see onscreen. For example, words in menus or dialog boxes appear in the text like this. Here is an example: "Select System info from the Administration panel."

Feedback from our readers is always welcome.

General feedback: If you have questions about any aspect of this book, mention the book title in the subject of your message and email us at customercare@packtpub.com.

Errata: Although we have taken every care to ensure the accuracy of our content, mistakes do happen. If you have found a mistake in this book, we would be grateful if you would report this to us. Please visit www.packt.com/submit-errata, selecting your book, clicking on the Errata Submission Form link, and entering the details.

Piracy: If you come across any illegal copies of our works in any form on the Internet, we would be grateful if you would provide us with the location address or website name. Please contact us at copyright@packt.com with a link to the material.

If you are interested in becoming an author: If there is a topic that you have expertise in and you are interested in either writing or contributing to a book, please visit authors.packtpub.com.

Please leave a review. Once you have read and used this book, why not leave a review on the site that you purchased it from? Potential readers can then see and use your unbiased opinion to make purchase decisions, we at Packt can understand what you think about our products, and our authors can see your feedback on their book. Thank you!

For more information about Packt, please visit packt.com.

In 2001, Martin Odersky started to design the Scala language =E2=80=93 it took him three years to release the first public version. The name comes from Scalable language. This was chosen because Scala is designed to grow with the requirements of its users =E2=80=93 you can use Scala for small scripts or for large enterprise applications.

Scala has been constantly evolving ever since, with a growing popularity. As a general purpose language, it is used in many different industries such as finance, telecoms, retail, and media. It is particularly compelling in distributed scalable systems and big data processing. Many leading open source software projects have been developed in Scala, such as Apache Spark, Apache Kafka, Finagle (by Twitter), and Akka. A large number of companies use Scala in production, such as Morgan Stanley, Barclays, Twitter, LinkedIn, The Guardian, and Sony.

Scala is not an extension of Java but is fully interoperable with it. You can call Java code from Scala, and you can call Scala code from Java. There is also a compiler to JavaScript, which we will explore later on in this book. You can, therefore, run Scala code in your browser.

Scala is a blend of object-oriented and functional programming paradigms, and it is statically typed. As such, it can serve as a bridge for people from an object-oriented or imperative background to move gradually to functional programming.

In this chapter, we will cover the following topics:

• Setting up your environment
• Using the basic features
• Running the Scala Console
• Using the Scala Console and Worksheet
• Creating my first project

First things first, we need to set up our work environment. In this section, we will get all the tools and libraries, and then install and configure them on your computer.

Scala programs are compiled to Java bytecode, which is a kind of assembly language that can be executed using a Java Virtual Machine (JVM). You will, therefore, need to have a Java compiler and a JVM installed on your computer. The Java Development Kit (JDK) provides both components, alongside other tools.

You could develop in Scala using a simple text editor and compile your programs using the Scala Simple Build Tool (SBT). However, this would not be a pleasant nor productive experience. The majority of professional Scala developers use an Integrated Development Environment (IDE), which provides many helpful features such as syntax highlighting, autocompletion, code navigation, integration with SBT, and many more. The most widely used IDE for Scala is IntelliJ Idea from JetBrains, and this is the one we are going to install and use in this book. The other options are Scala IDE for Eclipse and ENSIME. ENSIME is an open source project that brings IDE-like features to popular text editors such as Emacs, Vim, Atom, Sublime, and VSC.

We are going to install the Oracle JDK, which includes a JVM and a Java compiler. On many Linux distributions, the open source OpenJDK is preinstalled. OpenJDK is fully compatible with the Oracle JDK, so if you already have it you do not need to install anything else to follow this book.

You might already have a Java SDK installed on your computer. We are going to check if this is the case. If you are using Windows, open a DOS Command Prompt. If you are using macOS or Linux, open a Terminal. After the prompt, type the following:

javac -version

If you have a JDK installed, the version of the installed compiler will be printed:

javac 1.8.0_112

If the version installed is greater than or equal to 1.8.0_112, you can skip the JDK installation. The version of Scala that we are going to use is compatible with JDK version 1.8 or 1.9.

If not, open the following URL, download the SDK for your platform, and follow the installation instructions given: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html.

Go to https://www.jetbrains.com/idea/download. Download the community edition for your platform. The ultimate edition offers more features, but we will not use them in this book.

The following are the steps to install IntelliJ IDEA:

1. Run IntelliJ Idea.
2. Select the Do not import settings option:

1. Choose a UI theme. I personally prefer Dracula, since a dark background saves battery on a laptop and is more gentle on the eyes:

1.  Create a desktop entry by checking the options given:

1. In the Create Launcher Script dialog window, check the create a script... checkbox. It will let you open files in IntelliJ from the command line:

1. Customize the plugins. For each component, click on Customize... or Disable All. We will not need most of the plugins. You can only select the following:

• Build Tools: Disable All.
• Version Controls: Only keep Git and GitHub.
• Test Tools: Disable All.
• Swing: Disable.
• Android: Disable.
• Other Tools: Disable All and keep Bytecode viewer, Terminal, and YAML.
• Plugin Development: Disable.

You can see the aforementioned plugins in the following screenshot:

1. Install the featured plugins=E2=80=94some additional plugins are proposed for you to install, such as the Scala plugin and a tool to learn the essential features of IntelliJ.

1. Click on the Install button for Scala and for the IDE Features Trainer, as shown in the following screenshot, and then proceed by clicking on Start using IntelliJ IDEA:

1. Click on Create New Project | Scala | sbt:

1. Fill in the following details, as shown in the following screenshot:

• Name: scala_fundamentals.
• JDK: Click on New and then select the installation directory of the Oracle JDK.
• sbt: Choose the version 1.0.4, check Sources.
• Scala: Choose the latest version 2.12.x, for instance 2.12.4 (IntelliJ lists all the possible versions and will download the one you choose), and check Sources.
• Click on Finish.

It is going to take some time depending on your internet connection's speed:

1. You should see the following project structure:

Go to https://www.jetbrains.com/idea/download. Download the community edition for your platform. The ultimate edition offers more features, but we will not use them in this book.

The following are the steps to install IntelliJ IDEA:

1. Run IntelliJ Idea.
2. Select the Do not import settings option:

1. Choose a UI theme. I personally prefer Dracula, since a dark background saves battery on a laptop and is more gentle on the eyes:

1.  Create a desktop entry by checking the options given:

1. In the Create Launcher Script dialog window, check the create a script... checkbox. It will let you open files in IntelliJ from the command line:

1. Customize the plugins. For each component, click on Customize... or Disable All. We will not need most of the plugins. You can only select the following:

• Build Tools: Disable All.
• Version Controls: Only keep Git and GitHub.
• Test Tools: Disable All.
• Swing: Disable.
• Android: Disable.
• Other Tools: Disable All and keep Bytecode viewer, Terminal, and YAML.
• Plugin Development: Disable.

You can see the aforementioned plugins in the following screenshot:

1. Install the featured plugins=E2=80=94some additional plugins are proposed for you to install, such as the Scala plugin and a tool to learn the essential features of IntelliJ.

1. Click on the Install button for Scala and for the IDE Features Trainer, as shown in the following screenshot, and then proceed by clicking on Start using IntelliJ IDEA:

1. Click on Create New Project | Scala | sbt:

1. Fill in the following details, as shown in the following screenshot:

• Name: scala_fundamentals.
• JDK: Click on New and then select the installation directory of the Oracle JDK.
• sbt: Choose the version 1.0.4, check Sources.
• Scala: Choose the latest version 2.12.x, for instance 2.12.4 (IntelliJ lists all the possible versions and will download the one you choose), and check Sources.
• Click on Finish.

It is going to take some time depending on your internet connection's speed:

1. You should see the following project structure:

Go to https://www.jetbrains.com/idea/download. Download the community edition for your platform. The ultimate edition offers more features, but we will not use them in this book.

The following are the steps to install IntelliJ IDEA:

1. Run IntelliJ Idea.
2. Select the Do not import settings option:

1. Choose a UI theme. I personally prefer Dracula, since a dark background saves battery on a laptop and is more gentle on the eyes:

1.  Create a desktop entry by checking the options given:

1. In the Create Launcher Script dialog window, check the create a script... checkbox. It will let you open files in IntelliJ from the command line:

1. Customize the plugins. For each component, click on Customize... or Disable All. We will not need most of the plugins. You can only select the following:

• Build Tools: Disable All.
• Version Controls: Only keep Git and GitHub.
• Test Tools: Disable All.
• Swing: Disable.
• Android: Disable.
• Other Tools: Disable All and keep Bytecode viewer, Terminal, and YAML.
• Plugin Development: Disable.

You can see the aforementioned plugins in the following screenshot:

1. Install the featured plugins=E2=80=94some additional plugins are proposed for you to install, such as the Scala plugin and a tool to learn the essential features of IntelliJ.

1. Click on the Install button for Scala and for the IDE Features Trainer, as shown in the following screenshot, and then proceed by clicking on Start using IntelliJ IDEA:

1. Click on Create New Project | Scala | sbt:

1. Fill in the following details, as shown in the following screenshot:

• Name: scala_fundamentals.
• JDK: Click on New and then select the installation directory of the Oracle JDK.
• sbt: Choose the version 1.0.4, check Sources.
• Scala: Choose the latest version 2.12.x, for instance 2.12.4 (IntelliJ lists all the possible versions and will download the one you choose), and check Sources.
• Click on Finish.

It is going to take some time depending on your internet connection's speed:

1. You should see the following project structure:

Go to https://www.jetbrains.com/idea/download. Download the community edition for your platform. The ultimate edition offers more features, but we will not use them in this book.

The following are the steps to install IntelliJ IDEA:

1. Run IntelliJ Idea.
2. Select the Do not import settings option:

1. Choose a UI theme. I personally prefer Dracula, since a dark background saves battery on a laptop and is more gentle on the eyes:

1.  Create a desktop entry by checking the options given:

1. In the Create Launcher Script dialog window, check the create a script... checkbox. It will let you open files in IntelliJ from the command line:

1. Customize the plugins. For each component, click on Customize... or Disable All. We will not need most of the plugins. You can only select the following:

• Build Tools: Disable All.
• Version Controls: Only keep Git and GitHub.
• Test Tools: Disable All.
• Swing: Disable.
• Android: Disable.
• Other Tools: Disable All and keep Bytecode viewer, Terminal, and YAML.
• Plugin Development: Disable.

You can see the aforementioned plugins in the following screenshot:

1. Install the featured plugins=E2=80=94some additional plugins are proposed for you to install, such as the Scala plugin and a tool to learn the essential features of IntelliJ.

1. Click on the Install button for Scala and for the IDE Features Trainer, as shown in the following screenshot, and then proceed by clicking on Start using IntelliJ IDEA:

1. Click on Create New Project | Scala | sbt:

1. Fill in the following details, as shown in the following screenshot:

• Name: scala_fundamentals.
• JDK: Click on New and then select the installation directory of the Oracle JDK.
• sbt: Choose the version 1.0.4, check Sources.
• Scala: Choose the latest version 2.12.x, for instance 2.12.4 (IntelliJ lists all the possible versions and will download the one you choose), and check Sources.
• Click on Finish.

It is going to take some time depending on your internet connection's speed:

1. You should see the following project structure:

Go to https://www.jetbrains.com/idea/download. Download the community edition for your platform. The ultimate edition offers more features, but we will not use them in this book.

The following are the steps to install IntelliJ IDEA:

1. Run IntelliJ Idea.
2. Select the Do not import settings option:

1. Choose a UI theme. I personally prefer Dracula, since a dark background saves battery on a laptop and is more gentle on the eyes:

1.  Create a desktop entry by checking the options given:

1. In the Create Launcher Script dialog window, check the create a script... checkbox. It will let you open files in IntelliJ from the command line:

1. Customize the plugins. For each component, click on Customize... or Disable All. We will not need most of the plugins. You can only select the following:

• Build Tools: Disable All.
• Version Controls: Only keep Git and GitHub.
• Test Tools: Disable All.
• Swing: Disable.
• Android: Disable.
• Other Tools: Disable All and keep Bytecode viewer, Terminal, and YAML.
• Plugin Development: Disable.

You can see the aforementioned plugins in the following screenshot:

1. Install the featured plugins=E2=80=94some additional plugins are proposed for you to install, such as the Scala plugin and a tool to learn the essential features of IntelliJ.

1. Click on the Install button for Scala and for the IDE Features Trainer, as shown in the following screenshot, and then proceed by clicking on Start using IntelliJ IDEA:

1. Click on Create New Project | Scala | sbt:

1. Fill in the following details, as shown in the following screenshot:

• Name: scala_fundamentals.
• JDK: Click on New and then select the installation directory of the Oracle JDK.
• sbt: Choose the version 1.0.4, check Sources.
• Scala: Choose the latest version 2.12.x, for instance 2.12.4 (IntelliJ lists all the possible versions and will download the one you choose), and check Sources.
• Click on Finish.

It is going to take some time depending on your internet connection's speed:

1. You should see the following project structure:

Go to https://www.jetbrains.com/idea/download. Download the community edition for your platform. The ultimate edition offers more features, but we will not use them in this book.

The following are the steps to install IntelliJ IDEA:

1. Run IntelliJ Idea.
2. Select the Do not import settings option:

1. Choose a UI theme. I personally prefer Dracula, since a dark background saves battery on a laptop and is more gentle on the eyes:

1.  Create a desktop entry by checking the options given:

1. In the Create Launcher Script dialog window, check the create a script... checkbox. It will let you open files in IntelliJ from the command line:

1. Customize the plugins. For each component, click on Customize... or Disable All. We will not need most of the plugins. You can only select the following:

• Build Tools: Disable All.
• Version Controls: Only keep Git and GitHub.
• Test Tools: Disable All.
• Swing: Disable.
• Android: Disable.
• Other Tools: Disable All and keep Bytecode viewer, Terminal, and YAML.
• Plugin Development: Disable.

You can see the aforementioned plugins in the following screenshot:

1. Install the featured plugins=E2=80=94some additional plugins are proposed for you to install, such as the Scala plugin and a tool to learn the essential features of IntelliJ.

1. Click on the Install button for Scala and for the IDE Features Trainer, as shown in the following screenshot, and then proceed by clicking on Start using IntelliJ IDEA:

1. Click on Create New Project | Scala | sbt:

1. Fill in the following details, as shown in the following screenshot:

• Name: scala_fundamentals.
• JDK: Click on New and then select the installation directory of the Oracle JDK.
• sbt: Choose the version 1.0.4, check Sources.
• Scala: Choose the latest version 2.12.x, for instance 2.12.4 (IntelliJ lists all the possible versions and will download the one you choose), and check Sources.
• Click on Finish.

It is going to take some time depending on your internet connection's speed:

1. You should see the following project structure:

Go to https://www.jetbrains.com/idea/download. Download the community edition for your platform. The ultimate edition offers more features, but we will not use them in this book.

The following are the steps to install IntelliJ IDEA:

1. Run IntelliJ Idea.
2. Select the Do not import settings option:

1. Choose a UI theme. I personally prefer Dracula, since a dark background saves battery on a laptop and is more gentle on the eyes:

1.  Create a desktop entry by checking the options given:

1. In the Create Launcher Script dialog window, check the create a script... checkbox. It will let you open files in IntelliJ from the command line:

1. Customize the plugins. For each component, click on Customize... or Disable All. We will not need most of the plugins. You can only select the following:

• Build Tools: Disable All.
• Version Controls: Only keep Git and GitHub.
• Test Tools: Disable All.
• Swing: Disable.
• Android: Disable.
• Other Tools: Disable All and keep Bytecode viewer, Terminal, and YAML.
• Plugin Development: Disable.

You can see the aforementioned plugins in the following screenshot:

1. Install the featured plugins=E2=80=94some additional plugins are proposed for you to install, such as the Scala plugin and a tool to learn the essential features of IntelliJ.

1. Click on the Install button for Scala and for the IDE Features Trainer, as shown in the following screenshot, and then proceed by clicking on Start using IntelliJ IDEA:

1. Click on Create New Project | Scala | sbt:

1. Fill in the following details, as shown in the following screenshot:

• Name: scala_fundamentals.
• JDK: Click on New and then select the installation directory of the Oracle JDK.
• sbt: Choose the version 1.0.4, check Sources.
• Scala: Choose the latest version 2.12.x, for instance 2.12.4 (IntelliJ lists all the possible versions and will download the one you choose), and check Sources.
• Click on Finish.

It is going to take some time depending on your internet connection's speed:

1. You should see the following project structure:

Go to https://www.jetbrains.com/idea/download. Download the community edition for your platform. The ultimate edition offers more features, but we will not use them in this book.

The following are the steps to install IntelliJ IDEA:

1. Run IntelliJ Idea.
2. Select the Do not import settings option:

1. Choose a UI theme. I personally prefer Dracula, since a dark background saves battery on a laptop and is more gentle on the eyes:

1.  Create a desktop entry by checking the options given:

1. In the Create Launcher Script dialog window, check the create a script... checkbox. It will let you open files in IntelliJ from the command line:

1. Customize the plugins. For each component, click on Customize... or Disable All. We will not need most of the plugins. You can only select the following:

• Build Tools: Disable All.
• Version Controls: Only keep Git and GitHub.
• Test Tools: Disable All.
• Swing: Disable.
• Android: Disable.
• Other Tools: Disable All and keep Bytecode viewer, Terminal, and YAML.
• Plugin Development: Disable.

You can see the aforementioned plugins in the following screenshot:

1. Install the featured plugins=E2=80=94some additional plugins are proposed for you to install, such as the Scala plugin and a tool to learn the essential features of IntelliJ.

1. Click on the Install button for Scala and for the IDE Features Trainer, as shown in the following screenshot, and then proceed by clicking on Start using IntelliJ IDEA:

1. Click on Create New Project | Scala | sbt:

1. Fill in the following details, as shown in the following screenshot:

• Name: scala_fundamentals.
• JDK: Click on New and then select the installation directory of the Oracle JDK.
• sbt: Choose the version 1.0.4, check Sources.
• Scala: Choose the latest version 2.12.x, for instance 2.12.4 (IntelliJ lists all the possible versions and will download the one you choose), and check Sources.
• Click on Finish.

It is going to take some time depending on your internet connection's speed:

1. You should see the following project structure:

Go to https://www.jetbrains.com/idea/download. Download the community edition for your platform. The ultimate edition offers more features, but we will not use them in this book.

The following are the steps to install IntelliJ IDEA:

1. Run IntelliJ Idea.
2. Select the Do not import settings option:

1. Choose a UI theme. I personally prefer Dracula, since a dark background saves battery on a laptop and is more gentle on the eyes:

1.  Create a desktop entry by checking the options given:

1. In the Create Launcher Script dialog window, check the create a script... checkbox. It will let you open files in IntelliJ from the command line:

1. Customize the plugins. For each component, click on Customize... or Disable All. We will not need most of the plugins. You can only select the following:

• Build Tools: Disable All.
• Version Controls: Only keep Git and GitHub.
• Test Tools: Disable All.
• Swing: Disable.
• Android: Disable.
• Other Tools: Disable All and keep Bytecode viewer, Terminal, and YAML.
• Plugin Development: Disable.

You can see the aforementioned plugins in the following screenshot:

1. Install the featured plugins=E2=80=94some additional plugins are proposed for you to install, such as the Scala plugin and a tool to learn the essential features of IntelliJ.

1. Click on the Install button for Scala and for the IDE Features Trainer, as shown in the following screenshot, and then proceed by clicking on Start using IntelliJ IDEA:

1. Click on Create New Project | Scala | sbt:

1. Fill in the following details, as shown in the following screenshot:

• Name: scala_fundamentals.
• JDK: Click on New and then select the installation directory of the Oracle JDK.
• sbt: Choose the version 1.0.4, check Sources.
• Scala: Choose the latest version 2.12.x, for instance 2.12.4 (IntelliJ lists all the possible versions and will download the one you choose), and check Sources.
• Click on Finish.

It is going to take some time depending on your internet connection's speed:

1. You should see the following project structure:

In this section, and in the rest of this book, we will highlight some key shortcuts in italics. I strongly encourage you to use and remember these shortcuts. They save a tremendous amount of time and will keep you focused on the task at hand. If you cannot remember a shortcut, you can use the mother of all shortcuts, Ctrl + Shift + A (Windows/Linux) or cmd + shift + A (macOS), and type the name of the action you are looking for.

If you are using IntelliJ for the first time, I find it useful to display all tool buttons. Go to the View menu, and check Toolbar and Tool buttons.

Now, let's have a look at our build configuration. SBT (short for Simple Build Tool) is the de facto build tool in the Scala community. Double-click on build.sbt:

name := 'scala_fundamentals"

version := "0.1"

scalaVersion := "2.12.4"

This file describes how SBT will compile, test, and deploy our project. For now, it is fairly simple.

One important thing to keep in mind is that IntelliJ manages its own set of files to define a project structure. They are located in the .idea directory of your project.
Whenever you change build.sbt, IntelliJ has to interpret the changes and translate them.

For instance, If I change the Scala version to 2.12.3 and save (Ctrl + S or cmd + S), IntelliJ will propose to synchronize the changes or enable autoimport:

On a small project, it is ok to use autoimport, but on a large one, it can be a bit annoying. The synchronization can take time and it might kick off too often.

When you program in Scala using IntelliJ, you therefore have two ways of compiling your project:

• SBT, in which case you would only use IntelliJ as an advanced text editor
• IntelliJ

You could, in theory, mix and match: start building with SBT and continue with IntelliJ or the other way around. However, I strongly discourage you to do so, as you may get some unexpected compilation errors. When you want to switch to one tool or the other, it is best to clean all compiled files first.

We will further expand on SBT later in this book, but for now, we are only going to use IntelliJ's own build.

The project has been created and ready to be built. The build process does the following:

• Compiles the source files present at the source path and the test path
• Copies any resource files needed in the output path
• Reports any errors/warnings in the Message tool window

There are two ways to build the project:

• If you want to build your project incrementally, go to Build | Build Project (Ctrl + F9 or cmd + F9)
• If you want to delete all files and rebuild everything, go to Build | Rebuild All

As we do not have a source yet, the build is fast and no errors should appear in the Message tool window.

In IntelliJ, you need to have a run configuration whenever you want to run something: a program, a unit test, an external tool. A run configuration sets up the classpath, arguments, and environment variables that you need to run your executable.

We need to create a run configuration the first time we want to run the Scala console:

1. Go to Run | Edit Configurations. Click on the green + button, and select Scala Console. You should see the following screen:

1. Make the following changes and click OK:

• Name: Scala Console.
• Check Single instance only box =E2=80=93 we rarely need to have two consoles running at the same time.
• In, Before launch, click on Build and then click the Remove button. This way, you will always be able to quickly run a console, even if your code does not compile.
• Following that, click on OK.

1.  On the top toolbar, you should see that IntelliJ created a new Scala Console run configuration:

1. Click on the green arrow to run the console. You should see the following at the bottom of the screen, in the Run window. We can now type our first Scala expression after the Scala prompt:

In IntelliJ, you need to have a run configuration whenever you want to run something: a program, a unit test, an external tool. A run configuration sets up the classpath, arguments, and environment variables that you need to run your executable.

We need to create a run configuration the first time we want to run the Scala console:

1. Go to Run | Edit Configurations. Click on the green + button, and select Scala Console. You should see the following screen:

1. Make the following changes and click OK:

• Name: Scala Console.
• Check Single instance only box =E2=80=93 we rarely need to have two consoles running at the same time.
• In, Before launch, click on Build and then click the Remove button. This way, you will always be able to quickly run a console, even if your code does not compile.
• Following that, click on OK.

1.  On the top toolbar, you should see that IntelliJ created a new Scala Console run configuration:

1. Click on the green arrow to run the console. You should see the following at the bottom of the screen, in the Run window. We can now type our first Scala expression after the Scala prompt:

In IntelliJ, you need to have a run configuration whenever you want to run something: a program, a unit test, an external tool. A run configuration sets up the classpath, arguments, and environment variables that you need to run your executable.

We need to create a run configuration the first time we want to run the Scala console:

1. Go to Run | Edit Configurations. Click on the green + button, and select Scala Console. You should see the following screen:

1. Make the following changes and click OK:

• Name: Scala Console.
• Check Single instance only box =E2=80=93 we rarely need to have two consoles running at the same time.
• In, Before launch, click on Build and then click the Remove button. This way, you will always be able to quickly run a console, even if your code does not compile.
• Following that, click on OK.

1.  On the top toolbar, you should see that IntelliJ created a new Scala Console run configuration:

1. Click on the green arrow to run the console. You should see the following at the bottom of the screen, in the Run window. We can now type our first Scala expression after the Scala prompt:

By now, all the necessary tools and libraries should be installed. Let's start to play with the basics of Scala by experimenting in different environments. The simplest way to try Scala is to use the Scala Console. Subsequently, we will introduce the Scala Worksheet, which allows you to keep all the instructions that are entered in a file.

The Scala console, also called Scala REPL (short for Read-Eval-Print-Loop), allows you to execute bits of code without having to compile them beforehand. It is a very convenient tool to experiment with the language or when you want to explore the capabilities of a library.

In the console, type 1+1 after the scala> prompt and hit Ctrl + Enter or cmd + Enter:

scala> 1+1

The console displays the result of the evaluation, like so:

res0: Int = 2

What happened here? The REPL compiled, evaluated the expression 1+1, and automatically assigned it to a variable named res0. This variable is of type Int, and its value is 2.

In Scala, a variable can be declared using val or var. A val is immutable, which means you can never change its value. A var is mutable. It is not mandatory to declare the type of the variable. If you do not declare it, Scala will infer it for you.

Let's define some immutable variables:

scala> val x = 1 + 1
x: Int = 2

scala> val y: Int = 1 + 1
y: Int = 2

In both cases, the type of the variable is Int. The type of x was inferred by the compiler to be Int. The type of y was explicitly specified with : Int after the name of the variable.

We can define a mutable variable and modify it as follows:

scala> var x = 1
x: Int = 1

scala> x = 2
x: Int = 2

It is a good practice to use val in most situations. Whenever I see a val declared, I know that its content will never change subsequently. It helps to reason about a program, especially when multiple threads are running. You can share an immutable variable across multiple threads without fearing that one thread might see a different value at some point. Whenever you see a Scala program using var, it should make you raise an eyebrow: the programmer should have a good reason to use a mutable variable, and it should be documented.

If we attempt to modify a val, the compiler will raise an error message:

scala> val y = 1
y: Int = 1

scala> y = 2
:12: error: reassignment to val
       y = 2
         ^

This is a good thing: the compiler helps us make sure that no piece of code can ever modify a val.

We saw in the previous examples that Scala expressions have a type. For instance, the value 1 is of type Int, and the expression 1+1 is also of type Int. A type is a classification of data and provides a finite or infinite set of values. An expression of a given type can take any of its provided values.

Here are a few examples of types available in Scala:

• Int provides a finite set of values, which are all the integers between -2³¹ and 2³¹-1.
• Boolean provides a finite set of two values: true and false.
• Double provides a finite set of values: all the 64 bits and IEEE-754 floating point numbers.
• String provides an infinite set of values: all the sequence of characters are of an arbitrary length. For instance, "Hello World" or "Scala is great !".

A type determines the operations that can be performed on the data. For instance, you can use the + operator with two expressions of type Int or String, but not with expressions of type Boolean:

scala> val str = "Hello" + "World"
str: String = HelloWorld

scala> val i = 1 + 1
i: Int = 2

scala> val b = true + false
:11: error: type mismatch;
 found   : Boolean(false)

When we attempt to use an operation on a type that does not support it, the Scala compiler complains of a type mismatch error.

An important feature of Scala is that it is a statically typed language. This means that the type of a variable or expression is known at compile time. The compiler will also check that you do not call an operation or function that is not legal for this type. This helps tremendously to reduce the number of bugs that can occur at runtime (when running a program).

As we saw earlier, the type of an expression can be specified explicitly with : followed by the name of the type, or in many cases, it can be automatically inferred by the compiler.

If you are not used to working with statically typed languages, you might get frustrated to have to fight with the compiler to make it accept your code, but you will gradually get more accustomed to the kind of errors thrown at you and how to resolve them. You will soon find that the compiler is not an enemy that prevents you from running your code; it is acting more like a good friend that shows you what logical errors you have made and gives you some indication on how to resolve them.

People coming from dynamically typed languages such as Python, or people coming from not-as-strongly statically typed language such as Java or C++, are often astonished to see that a Scala program that compiles has a much higher probability of being correct on the first run.

A Scala function takes 0 to n parameters and returns a value. The type of each parameter must be declared. The type of the returned value is optional, as it is inferred by the Scala compiler when not specified. However, it is a good practice to always specify the return type, as it makes the code more readable:

scala> def presentation(name: String, age: Int): String = 
  "Hello, my name is " + name + ". I am " + age + " years old."
presentation: (name: String, age: Int)String

scala> presentation(name = "Bob", age = 25)
res1: String = Hello, my name is Bob. I am 25 years old.

scala> presentation(age = 25, name = "Bob")

res2: String = Hello, my name is Bob. I am 25 years old.

We can call a function by passing arguments in the right order, but we can also name the arguments and pass them in any order. It is a good practice to name the arguments when some of them have the same type, or when a function takes many arguments. It avoids passing the wrong argument and improves readability.

A function or expression is said to have a side effect when it modifies some state or has some action in the outside world. For instance, printing a string to the console, writing to a file, and modifying a var, are all side effects.

In Scala, all expressions have a type. A statement which performs a side effect is of type Unit. The only value provided by the type Unit is ():

scala> val x = println("hello")
hello
x: Unit = ()

scala> def printName(name: String): Unit = println(name)
printName: (name: String)Unit

scala> val y = {
  var a = 1
  a = a+1
}
y: Unit = ()

scala> val z = ()
z: Unit = ()

A pure function is a function whose result depends only on its arguments, and that does not have any observable side effect. Scala allows you to mix side-effecting code with pure code, but it is a good practice to push side-effecting code to the boundaries of your application. We will talk about this later in more detail in the Ensuring referential transparency section in Chapter 3, Handling Errors.

Here is an example of a method call with a side effect where we have to use empty brackets, and an example of a pure function:

scala> def helloWorld(): Unit = println("Hello world")
helloWorld: ()Unit

scala> helloWorld()
Hello world

scala> def helloWorldPure: String = "Hello world"
helloWorldPure: String

scala> val x = helloWorldPure
x: String = Hello world

In Scala, if (condition) ifExpr else if ifExpr2 else elseExpr is an expression, and has a type. If all sub-expressions have a type A, the type of the if ... else expression will be A as well:

scala> def agePeriod(age: Int): String = {
  if (age >= 65)
    "elderly"
  else if (age >= 40 && age < 65)
    "middle aged"
  else if (age >= 18 && age < 40)
    "young adult"
  else
    "child"
}
agePeriod: (age: Int)String

 If sub-expressions have different types, the compiler will infer a common super-type, or widen the type if it is a numeric type:

scala> val ifElseWiden = if (true) 2: Int else 2.0: Double
ifElseWiden: Double = 2.0

scala> val ifElseSupertype = if (true) 2 else "2"
ifElseSupertype: Any = 2

In the first expression present in the preceding code, the first sub-expression is of type Int and the second is of type Double. The type of ifElseWiden is widened to be Double.

In the second expression, the type of ifElseSupertype is Any, which is the common super-type for Int and String.

An if without an else is equivalent to if (condition) ifExpr else (). It is better to always specify the else expression, otherwise, the type of the if/else expression might not be the one we expect:

scala> val ifWithoutElse = if (true) 2
ifWithoutElse: AnyVal = 2
 
scala> val ifWithoutElseExpanded = if (true) 2: Int else (): Unit
ifWithoutElseExpanded: AnyVal = 2
 
scala> def sideEffectingFunction(): Unit = if (true) println("hello world")
sideEffectingFunction: ()Unit

In the preceding code, the common super-type between Int and Unit is AnyVal. This can be a bit surprising. In most situations, you would want to avoid that. 

We mentioned earlier that all Scala expressions have a type. A class is a sort of template that can create objects of a specific type. When we want to obtain a value of a certain type, we can instantiate a new object using new followed by the class name:

scala> class Robot
defined class Robot

scala> val nao = new Robot
nao: Robot = Robot@78318ac2

The instantiation of an object allocates a portion of heap memory in the JVM. In the preceding example, the value nao is actually a reference to the portion of heap memory that keeps the content of our new Robot object. You can observe that when the Scala console printed the variable nao, it outputted the name of the class, followed by @78318ac2. This hexadecimal number is, in fact, the memory address of where the object is stored in the heap.

The eq operator can be handy to check if two references are equal. If they are equal, this means that they point to the same portion of memory:

scala> val naoBis = nao
naoBis: Robot = Robot@78318ac2

scala> nao eq naoBis
res0: Boolean = true

scala> val johnny5 = new Robot
johnny5: Robot = Robot@6b64bf61

scala> nao eq johnny5
res1: Boolean = false

A class can have zero to many members. A member can be either:

• An attribute, also called a field. It is a variable whose content is unique to each instance of the class.
• A method. This is a function that can read and/or write the attributes of the instance. It can have additional parameters.

Here is a class that defines a few members:

scala> class Rectangle(width: Int, height: Int) {
  val area: Int = width * height
  def scale(factor: Int): Rectangle = new Rectangle(width * factor, height * factor)
}
defined class Rectangle

The attributes declared inside the brackets () are a bit special: they are constructor arguments, which means that their value must be specified when we instantiate a new object of the class. The other members must be defined inside the curly brackets {}. In our example, we defined four members:

• Two attributes that are constructor arguments: width and height.
• One attribute, area. Its value is defined when an instance is created by using the other attributes.
• One method, scale, which uses the attributes to create a new instance of the class Rectangle.

You can call a member on an instance of a class by using the postfix notation myInstance.member. Let's create a few instances of our class and try to call the members:

scala> val square = new Rectangle(2, 2)
square: Rectangle = Rectangle@2af9a5ef

scala> square.area
res0: Int = 4

scala> val square2 = square.scale(2)
square2: Rectangle = Rectangle@8d29719

scala> square2.area
res1: Int = 16

scala> square.width
:13: error: value width is not a member of Rectangle
       square.width

We can call the members area and scale, but not width. Why is that?

This is because, by default, constructor arguments are not accessible from the outside world. They are private to the instance and can only be accessed from the other members. If you want to make the constructor arguments accessible, you need to prefix them with val:

scala> class Rectangle(val width: Int, val height: Int) {
  val area: Int = width * height
  def scale(factor: Int): Rectangle = new Rectangle(width * factor, height * factor)
}
defined class Rectangle

scala> val rect = new Rectangle(3, 2)
rect: Rectangle = Rectangle@3dbb7bb

scala> rect.width
res3: Int = 3

scala> rect.height
res4: Int = 2

This time, we can get access to the constructor arguments. Note that you can declare attributes using var instead of val. This would make your attribute modifiable. However, in functional programming, we avoid mutating variables. A var attribute in a class is something that should be used cautiously in specific situations. An experienced Scala programmer would flag it immediately in a code review and its usage should be always justified in a code comment.

If you need to modify an attribute, it is better to return a new instance of the class with the modified attribute, as we did in the preceding Rectangle.scale method.

IntelliJ offers another handy tool to experiment with the language: the Scala worksheet.

Go to File | New | Scala Worksheet. Name it worksheet.sc. You can then enter some code on the left-hand side of the screen. A red/green indicator in the top right corner shows you if the code you are typing is valid or not. As soon as it compiles, the results appear on the right-hand side:

You will notice that nothing gets evaluated until your whole worksheet compiles.

Scala classes are extensible. You can extend an existing class to inherit from all its members. If B extends A, we say that B is a subclass of A, a derivation of B, or a specialization of B. A is a superclass of B or a generalization of B.

Let's see how it works in an example. Type the following code in the worksheet:

class Shape(val x: Int, val y: Int) {
  val isAtOrigin: Boolean = x == 0 && y == 0
}

class Rectangle(x: Int, y: Int, val width: Int, val height: Int)
  extends Shape(x, y)

class Square(x: Int, y: Int, width: Int)
  extends Rectangle(x, y, width, width)

class Circle(x: Int, y: Int, val radius: Int)
  extends Shape(x, y)

val rect = new Rectangle(x = 0, y = 3, width = 3, height = 2)
rect.x
rect.y
rect.isAtOrigin
rect.width
rect.height

The classes Rectangle and Circle are subclasses of Shape. They inherit from all the members of Shape: x, y, and isAtOrigin. This means that when I instantiate a new Rectangle, I can call members declared in Rectangle, such as width and height, and I can also call members declared in Shape.

When declaring a subclass, you need to pass the constructor arguments of the superclass, as if you were instantiating it. As Shape declares two constructor parameters, x and y, we have to pass them in the declaration extends Shape(x, y). In this declaration, x and y are themselves the constructor arguments of Rectangle. We just passed these arguments up the chain.

Notice that in the subclasses, the constructor parameters x and y are declared without val. If we had declared them with val, they would have been promoted as publicly available attributes. The problem is that Shape also has x and y as public attributes. In this situation, the compiler would have raised a compilation error to highlight the conflict.

Consider two classes, A and B, with B extends A.

When you declare a variable of type A, you can assign it to an instance of B, with val a: A = new B.

On the other hand, if you declare a variable of type B, you cannot assign it to an instance of A.

Here is an example that uses the same Shape and Rectangle definitions that were described earlier:

val shape: Shape = new Rectangle(x = 0, y = 3, width = 3, height = 2)
val rectangle: Rectangle = new Shape(x = 0, y = 3)

The first line compiles because Rectangle is a Shape.

The second line does not compile, because not all shapes are rectangles.

When you derive a class, you can override the members of the superclass to provide a different implementation. Here is an example that you can retype in a new worksheet:

class Shape(val x: Int, val y: Int) {
  def description: String = s"Shape at (" + x + "," + y + ")"
}

class Rectangle(x: Int, y: Int, val width: Int, val height: Int)
  extends Shape(x, y) {
  override def description: String = {
    super.description + s" - Rectangle " + width + " * " + height
  }
}

val rect = new Rectangle(x = 0, y = 3, width = 3, height = 2)
rect.description

When you run the worksheet, it evaluates and prints the following description on the right-hand side:

res0: String = Shape at (0,3) - Rectangle 3 * 2

We defined a method description on the class Shape that returns a String. When we call rect.description, the method called is the one defined in the class Rectangle, because Rectangle overrides the method description with a different implementation.

The implementation of description in the class Rectangle refers to super.description. super is a keyword that lets you use the members of the superclass without taking into account any overriding. In our case, this was necessary so that we could use the super reference, otherwise, description would have called itself in an infinite loop!

On the other hand, the keyword this allows you to call the members of the same class. Change Rectangle to add the following methods:

class Rectangle(x: Int, y: Int, val width: Int, val height: Int)
  extends Shape(x, y) {
  override def description: String = {
    super.description + s" - Rectangle " + width + " * " + height
  }

  def descThis: String = this.description
  def descSuper: String = super.description
}

val rect = new Rectangle(x = 0, y = 3, width = 3, height = 2)
rect.description
rect.descThis
rect.descSuper

When you evaluate the worksheet, it prints the following strings:

res0: String = Shape at (0,3) - Rectangle 3 * 2
res1: String = Shape at (0,3) - Rectangle 3 * 2
res2: String = Shape at (0,3)

The call to this.description used the definition of description, as declared in the class Rectangle, whereas the call to super.description used the definition of description, as declared in the class Shape.

An abstract class is a class that can have many abstract members. An abstract member defines only a signature for an attribute or a method, without providing any implementation. You cannot instantiate an abstract class: you must create a subclass that implements all the abstract members.

Replace the definition of Shape and Rectangle in the worksheet as follows:

abstract class Shape(val x: Int, val y: Int) {
  val area: Double
  def description: String
}

class Rectangle(x: Int, y: Int, val width: Int, val height: Int)
  extends Shape(x, y) {

  val area: Double = width * height

  def description: String =
    "Rectangle " + width + " * " + height
}

Our class Shape is now abstract. We cannot instantiate a Shape class directly anymore: we have to create an instance of Rectangle or any of the other subclasses of Shape. Shape defines two concrete members, x and y, and two abstract members, area and description. The subclass, Rectangle, implements the two abstract members.

A trait is similar to an abstract class: it can declare several abstract or concrete members and can be extended. It cannot be instantiated. The difference is that a given class can only extend one abstract class, however, it can mixin one to many traits. Also, a trait cannot have constructor arguments.

For instance, we can declare several traits, each declaring different abstract methods, and mixin them all in the Rectangle class:

trait Description {
  def description: String
}

trait Coordinates extends Description {
  def x: Int
  def y: Int

  def description: String =
    "Coordinates (" + x + ", " + y + ")"
}

trait Area {
  def area: Double
}

class Rectangle(val x: Int,
                val y: Int,
                val width: Int,
                val height: Int)
  extends Coordinates with Description with Area {

  val area: Double = width * height

  override def description: String =
    super.description + " - Rectangle " + width + " * " + height
}

val rect = new Rectangle(x = 0, y = 3, width = 3, height = 2)
rect.description

The following string gets printed when evaluating rect.description:

res0: String = Coordinates (0, 3) - Rectangle 3 * 2

The class Rectangle mixes in the traits Coordinates, Description, and Area. We need to use the keyword extends before trait or class, and the keyword with for all subsequent traits.

Notice that the Coordinates trait also mixes the Description trait, and provides a default implementation. As we did when we had a Shape class, we override this implementation in Rectangle, and we can still call super.description to refer to the implementation of description in the trait Coordinates.

Another interesting point is that you can implement an abstract method with val =E2=80=93 in trait Area, we defined def area: Double, and implemented it in Rectangle using val area: Double. It is a good practice to define abstract members with def. This way, the implementer of the trait can decide whether to define it by using a method or a variable.

All Scala types extend a built-in type called Any. This type is the root of the hierarchy of all Scala types. It has two direct subtypes:

• AnyVal is the root class of all value types. These types are represented as primitive types in the JVM.
• AnyRef is the root class of all object types. It is an alias for the class java.lang.Object.
• A variable of type AnyVal directly contains the value, whereas a variable of type AnyRef contains the address of an object stored somewhere in memory.

The following diagram shows a partial view of this hierarchy:

When you define a new class, it indirectly extends AnyRef. This being an alias for java.lang.Object, your class inherits from all the default methods implemented in Object. Its most important methods are as follows:

• def toString: String returns a string representation of an object. This method is called whenever you print an object using println. The default implementation returns the class's name followed by the address of the object in memory.
• def equals(obj: Object): Boolean returns true if the object is equal to another object, and false otherwise. This method is called whenever you compare two objects using =3D=3D. The default implementation only compares the objects' references, and hence is equivalent to eq. Fortunately, most classes from the Java and Scala SDK override this method to provide a good comparison. For instance, the class java.lang.String overrides the equals method to compare the content of the strings, character by character. Therefore, when you compare two strings with =3D=3D, the result will be true if the strings are the same, even if they are stored in different places in memory.
• def hashCode: Int is called whenever you put an object in Set or if you use it as a key in Map. The default implementation is based on the address of the object. You can override this method if you want to have a better distribution of the data in Set or Map, which can improve the performance of these collections. However, if you do so, you must make sure that hashCode is consistent with equals: if two objects are equal, their hashCodes must also be equal.

It would be very tedious to have to override these methods for all your classes. Fortunately, Scala offers a special construct called case class that will automatically override these methods for us.

In Scala, we define most data structures using case classes. case class has one to many immutable attributes and provides several built-in functions compared to a standard class.

Type the following into the worksheet:

case class Person(name: String, age: Int)
val mikaelNew = new Person("Mikael", 41)
// 'new' is optional
val mikael = Person("Mikael", 41)
// == compares values, not references
mikael == mikaelNew
// == is exactly the same as .equals
mikael.equals(mikaelNew)
 
val name = mikael.name
 
// a case class is immutable. The line below does not compile:
//mikael.name = "Nicolas"
// you need to create a new instance using copy
val nicolas = mikael.copy(name = "Nicolas")

In the preceding code, the text following // is a comment that explains the preceding statement.

When you declare a class as case class, the Scala compiler automatically generates a default constructor, an equals and hashCode method, a copy constructor, and an accessor for each attribute.

Here is a screenshot of the worksheet we have. You can see the results of the evaluations on the right-hand side:

A class can have a companion object. It must be declared in the same file as the class, using the keyword object followed by the name of the class it is accompanying. A companion object is a singleton =E2=80=93 there is only one instance of this object in the JVM. It has its own type and is not an instance of the accompanied class.

This object defines static functions or values that are closely related to the class it is accompanying. If you are familiar with Java, it replaces the keyword static: in Scala, all static members of a class are declared inside the companion object.

Some functions in the companion object have a special meaning. Functions named apply are constructors of the class. The name apply can be omitted when we call them:

case class City(name: String, urbanArea: Int)
object City {
  val London = City("London", 1738)
  val Lausanne = City("Lausanne", 41)
}
 
case class Person(firstName: String, lastName: String, city: City)
object Person {
  def apply(fullName: String, city: City): Person = {
    val splitted = fullName.split(" ")
    new Person(firstName = splitted(0), lastName = splitted(1), city = city)
  }
}

// Uses the default apply method
val m1 = Person("Mikael", "Valot", City.London)
// Call apply with fullName
val m2 = Person("Mikael Valot", City.London)
// We can omit 'apply'
val n = Person.apply("Nicolas Jorand", City.Lausanne)

In the preceding code, we defined a companion object for the class City, which defines some constants. The convention for constants is to have the first letter in uppercase.

The companion object for the class Person defines an additional apply function that acts as a constructor. Its implementation calls the method split(" "), which splits a string separated by spaces to produce an array of type string. It allows us to construct a Person instance using a single string where the first name and last name are separated by a space. We then demonstrated that we can either call the default apply function that comes with the case class, or the one we implemented.

As you now know the basics of running code in the REPL and the worksheet, it is time to create your first 'Hello World' project. In this section, we are going to filter a list of people and print their name and age into the console.

Repeat the same recipe that you completed in the Installing IntelliJ section to create a new project. Here is a summary of the tasks you must complete:

1. Run IntelliJ and select Create New Project
2. Select Scala and sbt
3. Input the name of the project, such as Examples
4. If the selected directory doesn't exist, IntelliJ will ask you if you want to create it =E2=80=93 select OK

As soon as you accept that you are going to create the directory, IntelliJ is going to download all the necessary dependencies and build the project structure. Be patient, as this could take a while, especially if you do not have a good internet connection.

Once everything is downloaded, you should have your IDE in the following state:

Notice the folder structure. The source code is under src/main/scala and the test code is under src/test/scala. If you have used Maven before, this structure should sound familiar.

Here we are! Let's create our first application. First, create the entry point for the program. If you are coming from Java, it would be equivalent to defining the public static void main(String[] args).

Right-click on the src/main/scala folder and select New | Scala Class. Give Main as the class name and Object as the Kind:

We have created our first object. This object is a singleton. There can be only one instance of it in the JVM. The equivalent in Java would be a static class with static methods.

We would like to use it as the main entry point of our program. Scala provides a convenient class named App that needs to be extended. Let's extend our Main object with that class:

object Main extends App {

}

The App superclass defines a static main method that will execute all the code defined inside your Main object. That's all =E2=80=93 we created our first version, which does nothing!

We can now run the program in IntelliJ. Click on the small green triangle in the gutter of the object definition, as follows:

The program gets compiled and executed, as shown in the following screenshot:

It is not spectacular, but let's improve it. To get the right habits, we are going to use the TDD technique to proceed further.

Here we are! Let's create our first application. First, create the entry point for the program. If you are coming from Java, it would be equivalent to defining the public static void main(String[] args).

Right-click on the src/main/scala folder and select New | Scala Class. Give Main as the class name and Object as the Kind:

We have created our first object. This object is a singleton. There can be only one instance of it in the JVM. The equivalent in Java would be a static class with static methods.

We would like to use it as the main entry point of our program. Scala provides a convenient class named App that needs to be extended. Let's extend our Main object with that class:

object Main extends App {

}

The App superclass defines a static main method that will execute all the code defined inside your Main object. That's all =E2=80=93 we created our first version, which does nothing!

We can now run the program in IntelliJ. Click on the small green triangle in the gutter of the object definition, as follows:

The program gets compiled and executed, as shown in the following screenshot:

It is not spectacular, but let's improve it. To get the right habits, we are going to use the TDD technique to proceed further.

Here we are! Let's create our first application. First, create the entry point for the program. If you are coming from Java, it would be equivalent to defining the public static void main(String[] args).

Right-click on the src/main/scala folder and select New | Scala Class. Give Main as the class name and Object as the Kind:

We have created our first object. This object is a singleton. There can be only one instance of it in the JVM. The equivalent in Java would be a static class with static methods.

We would like to use it as the main entry point of our program. Scala provides a convenient class named App that needs to be extended. Let's extend our Main object with that class:

object Main extends App {

}

The App superclass defines a static main method that will execute all the code defined inside your Main object. That's all =E2=80=93 we created our first version, which does nothing!

We can now run the program in IntelliJ. Click on the small green triangle in the gutter of the object definition, as follows:

The program gets compiled and executed, as shown in the following screenshot:

It is not spectacular, but let's improve it. To get the right habits, we are going to use the TDD technique to proceed further.

TDD is a very powerful technique to write efficient, modular, and safe programs. It is very simple, and there are only three rules to play this game:

1. You are not allowed to write any production code unless it is to make a failing unit test pass.
2. You are not allowed to write any more of a unit test than is sufficient to fail, and compilation failures are failures.
3. You are not allowed to write any more production code than is sufficient to pass the one failing unit test.

There are multiple testing frameworks in Scala, but we chose ScalaTest (http://www.scalatest.org/) for its simplicity.

In order to add the ScalaTest library in the project, follow these steps:

1. Edit the build.sbt file.
2. Add a new repository resolver to search for Scala libraries.
3. Add the ScalaTest library:

name := "Examples"
version := "0.1"
scalaVersion := "2.12.4"
resolvers += "Artima Maven Repository" at "http://repo.artima.com/releases"
libraryDependencies += "org.scalatest" %% "scalatest" % "3.0.4" % "test"

1. Create the test class by right-clicking on the test/scala folder and clicking on create a new class. Name it MainSpec.

ScalaTest offers multiple ways to define your test =E2=80=93 the full list can be found on the official website (http://www.scalatest.org/at_a_glance/WordSpec). We are going to use the WordSpec style since it is quite prescriptive, offers a hierarchical structure, and is commonly used on large Scala projects.

Your MainSpec should extend the WordSpec class and the Matchers class, like so:

class MainSpec extends WordSpec with Matchers {

}

WordSpec and Matchers are underlined in red, which means that the class is not resolved. To make it resolved, go with the cursor on the class and press Alt + Enter of your keyboard. If you are positioned on the WordSpec word, a popup should appear. This is normal, as there are several classes named WordSpec in different packages:

Select the first option and IntelliJ will automatically add the import on the top of your code. On the Matchers class, as soon as you type Alt + Enter, the import will be added directly.

The final code should be as follows:

import org.scalatest.{WordSpec, Matchers}

class MainSpec extends WordSpec with Matchers {

}

Our class skeleton is now ready for our first test. We would like to create the Person class and test its constructor.

Let's explain what we would like to test using simple sentences. Complete the test class with the following code:

class MainSpec extends WordSpec with Matchers {
  "A Person" should {
    "be instantiated with a age and name" in {
      val john = Person(firstName = "John", lastName =  "Smith", 42)
      john.firstName should be("John")
      john.lastName should be("Smith")
      john.age should be(42)
    }
  }
}

IntelliJ is complaining that it cannot resolve the symbols Person, name, surname, and age. This is expected since the Person class does not exist. Let's create it in the folder src/main/scala. Right-click on the folder and create a new class named Person.

Transform it in the case of the class by adding the case keyword and defining the constructor with the name, surname, and age:

case class Person(firstName: String, lastName: String, age: Int)

If you go back to the MainSpec.scala file, you'll notice that the class is now compiled without any error and warning. The green tick () on the top-right of the code window confirms this.

Run the test by right-clicking on the MainSpec.scala file and selecting Run 'MainSpec', or use the keyboard shortcut Ctrl + Shift + F10 or Ctrl + Shift + R:

The test contained in MainSpec runs and the results appear in the Run window:

TDD is a very powerful technique to write efficient, modular, and safe programs. It is very simple, and there are only three rules to play this game:

1. You are not allowed to write any production code unless it is to make a failing unit test pass.
2. You are not allowed to write any more of a unit test than is sufficient to fail, and compilation failures are failures.
3. You are not allowed to write any more production code than is sufficient to pass the one failing unit test.

There are multiple testing frameworks in Scala, but we chose ScalaTest (http://www.scalatest.org/) for its simplicity.

In order to add the ScalaTest library in the project, follow these steps:

1. Edit the build.sbt file.
2. Add a new repository resolver to search for Scala libraries.
3. Add the ScalaTest library:

name := "Examples"
version := "0.1"
scalaVersion := "2.12.4"
resolvers += "Artima Maven Repository" at "http://repo.artima.com/releases"
libraryDependencies += "org.scalatest" %% "scalatest" % "3.0.4" % "test"

1. Create the test class by right-clicking on the test/scala folder and clicking on create a new class. Name it MainSpec.

ScalaTest offers multiple ways to define your test =E2=80=93 the full list can be found on the official website (http://www.scalatest.org/at_a_glance/WordSpec). We are going to use the WordSpec style since it is quite prescriptive, offers a hierarchical structure, and is commonly used on large Scala projects.

Your MainSpec should extend the WordSpec class and the Matchers class, like so:

class MainSpec extends WordSpec with Matchers {

}

WordSpec and Matchers are underlined in red, which means that the class is not resolved. To make it resolved, go with the cursor on the class and press Alt + Enter of your keyboard. If you are positioned on the WordSpec word, a popup should appear. This is normal, as there are several classes named WordSpec in different packages:

Select the first option and IntelliJ will automatically add the import on the top of your code. On the Matchers class, as soon as you type Alt + Enter, the import will be added directly.

The final code should be as follows:

import org.scalatest.{WordSpec, Matchers}

class MainSpec extends WordSpec with Matchers {

}

Our class skeleton is now ready for our first test. We would like to create the Person class and test its constructor.

Let's explain what we would like to test using simple sentences. Complete the test class with the following code:

class MainSpec extends WordSpec with Matchers {
  "A Person" should {
    "be instantiated with a age and name" in {
      val john = Person(firstName = "John", lastName =  "Smith", 42)
      john.firstName should be("John")
      john.lastName should be("Smith")
      john.age should be(42)
    }
  }
}

IntelliJ is complaining that it cannot resolve the symbols Person, name, surname, and age. This is expected since the Person class does not exist. Let's create it in the folder src/main/scala. Right-click on the folder and create a new class named Person.

Transform it in the case of the class by adding the case keyword and defining the constructor with the name, surname, and age:

case class Person(firstName: String, lastName: String, age: Int)

If you go back to the MainSpec.scala file, you'll notice that the class is now compiled without any error and warning. The green tick () on the top-right of the code window confirms this.

Run the test by right-clicking on the MainSpec.scala file and selecting Run 'MainSpec', or use the keyboard shortcut Ctrl + Shift + F10 or Ctrl + Shift + R:

The test contained in MainSpec runs and the results appear in the Run window:

TDD is a very powerful technique to write efficient, modular, and safe programs. It is very simple, and there are only three rules to play this game:

1. You are not allowed to write any production code unless it is to make a failing unit test pass.
2. You are not allowed to write any more of a unit test than is sufficient to fail, and compilation failures are failures.
3. You are not allowed to write any more production code than is sufficient to pass the one failing unit test.

There are multiple testing frameworks in Scala, but we chose ScalaTest (http://www.scalatest.org/) for its simplicity.

In order to add the ScalaTest library in the project, follow these steps:

1. Edit the build.sbt file.
2. Add a new repository resolver to search for Scala libraries.
3. Add the ScalaTest library:

name := "Examples"
version := "0.1"
scalaVersion := "2.12.4"
resolvers += "Artima Maven Repository" at "http://repo.artima.com/releases"
libraryDependencies += "org.scalatest" %% "scalatest" % "3.0.4" % "test"

1. Create the test class by right-clicking on the test/scala folder and clicking on create a new class. Name it MainSpec.

ScalaTest offers multiple ways to define your test =E2=80=93 the full list can be found on the official website (http://www.scalatest.org/at_a_glance/WordSpec). We are going to use the WordSpec style since it is quite prescriptive, offers a hierarchical structure, and is commonly used on large Scala projects.

Your MainSpec should extend the WordSpec class and the Matchers class, like so:

class MainSpec extends WordSpec with Matchers {

}

WordSpec and Matchers are underlined in red, which means that the class is not resolved. To make it resolved, go with the cursor on the class and press Alt + Enter of your keyboard. If you are positioned on the WordSpec word, a popup should appear. This is normal, as there are several classes named WordSpec in different packages:

Select the first option and IntelliJ will automatically add the import on the top of your code. On the Matchers class, as soon as you type Alt + Enter, the import will be added directly.

The final code should be as follows:

import org.scalatest.{WordSpec, Matchers}

class MainSpec extends WordSpec with Matchers {

}

Our class skeleton is now ready for our first test. We would like to create the Person class and test its constructor.

Let's explain what we would like to test using simple sentences. Complete the test class with the following code:

class MainSpec extends WordSpec with Matchers {
  "A Person" should {
    "be instantiated with a age and name" in {
      val john = Person(firstName = "John", lastName =  "Smith", 42)
      john.firstName should be("John")
      john.lastName should be("Smith")
      john.age should be(42)
    }
  }
}

IntelliJ is complaining that it cannot resolve the symbols Person, name, surname, and age. This is expected since the Person class does not exist. Let's create it in the folder src/main/scala. Right-click on the folder and create a new class named Person.

Transform it in the case of the class by adding the case keyword and defining the constructor with the name, surname, and age:

case class Person(firstName: String, lastName: String, age: Int)

If you go back to the MainSpec.scala file, you'll notice that the class is now compiled without any error and warning. The green tick () on the top-right of the code window confirms this.

Run the test by right-clicking on the MainSpec.scala file and selecting Run 'MainSpec', or use the keyboard shortcut Ctrl + Shift + F10 or Ctrl + Shift + R:

The test contained in MainSpec runs and the results appear in the Run window:

TDD is a very powerful technique to write efficient, modular, and safe programs. It is very simple, and there are only three rules to play this game:

1. You are not allowed to write any production code unless it is to make a failing unit test pass.
2. You are not allowed to write any more of a unit test than is sufficient to fail, and compilation failures are failures.
3. You are not allowed to write any more production code than is sufficient to pass the one failing unit test.

There are multiple testing frameworks in Scala, but we chose ScalaTest (http://www.scalatest.org/) for its simplicity.

In order to add the ScalaTest library in the project, follow these steps:

1. Edit the build.sbt file.
2. Add a new repository resolver to search for Scala libraries.
3. Add the ScalaTest library:

name := "Examples"
version := "0.1"
scalaVersion := "2.12.4"
resolvers += "Artima Maven Repository" at "http://repo.artima.com/releases"
libraryDependencies += "org.scalatest" %% "scalatest" % "3.0.4" % "test"

1. Create the test class by right-clicking on the test/scala folder and clicking on create a new class. Name it MainSpec.

ScalaTest offers multiple ways to define your test =E2=80=93 the full list can be found on the official website (http://www.scalatest.org/at_a_glance/WordSpec). We are going to use the WordSpec style since it is quite prescriptive, offers a hierarchical structure, and is commonly used on large Scala projects.

Your MainSpec should extend the WordSpec class and the Matchers class, like so:

class MainSpec extends WordSpec with Matchers {

}

WordSpec and Matchers are underlined in red, which means that the class is not resolved. To make it resolved, go with the cursor on the class and press Alt + Enter of your keyboard. If you are positioned on the WordSpec word, a popup should appear. This is normal, as there are several classes named WordSpec in different packages:

Select the first option and IntelliJ will automatically add the import on the top of your code. On the Matchers class, as soon as you type Alt + Enter, the import will be added directly.

The final code should be as follows:

import org.scalatest.{WordSpec, Matchers}

class MainSpec extends WordSpec with Matchers {

}

Our class skeleton is now ready for our first test. We would like to create the Person class and test its constructor.

Let's explain what we would like to test using simple sentences. Complete the test class with the following code:

class MainSpec extends WordSpec with Matchers {
  "A Person" should {
    "be instantiated with a age and name" in {
      val john = Person(firstName = "John", lastName =  "Smith", 42)
      john.firstName should be("John")
      john.lastName should be("Smith")
      john.age should be(42)
    }
  }
}

IntelliJ is complaining that it cannot resolve the symbols Person, name, surname, and age. This is expected since the Person class does not exist. Let's create it in the folder src/main/scala. Right-click on the folder and create a new class named Person.

Transform it in the case of the class by adding the case keyword and defining the constructor with the name, surname, and age:

case class Person(firstName: String, lastName: String, age: Int)

If you go back to the MainSpec.scala file, you'll notice that the class is now compiled without any error and warning. The green tick () on the top-right of the code window confirms this.

Run the test by right-clicking on the MainSpec.scala file and selecting Run 'MainSpec', or use the keyboard shortcut Ctrl + Shift + F10 or Ctrl + Shift + R:

The test contained in MainSpec runs and the results appear in the Run window:

Now, we would like to have a nice representation of the person by stating his/her name and age. The test should look like the following:

"Get a human readable representation of the person" in {
  val paul = Person(firstName = "Paul", lastName = "Smith", age = 24)
  paul.description should be("Paul Smith is 24 years old")
}

Run the test again. We will get a compilation error:

This is expected as the function doesn't exist on the Person class. To implement it, add the expected implementation by setting the cursor on the description() error in the MainSpec.scala class, hitting Alt + Enter, and selecting the create method description.
IntelliJ generates the method for you and sets the implementation to ???. Replace ??? with the expected code:

def description = s"$firstName $lastName is $age ${if (age <= 1) "year"                    else "years"} old"

By doing so, we defined a method that does not take any parameter and return a string representing Person. In order to simplify the code, we are using a string interpolation to build the string. To use string interpolation, you just have to prepend an s before the first quote. Inside the quote, you can use the wildcard $ so that we can use an external variable and use the bracket after the dollar sign to enter more code than just a variable name.

Execute the test and the result should be green:

The next step is to write a utility function that, given a list of people, returns only the adults.

For the tests, two cases are defined:

"The Person companion object" should {
  val (akira, peter, nick) = (
    Person(firstName = "Akira", lastName = "Sakura", age = 12),
    Person(firstName = "Peter", lastName = "M=C3=BCller", age = 34),
    Person(firstName = "Nick", lastName = "Tagart", age = 52)
  )
  "return a list of adult person" in {
    val ref = List(akira, peter, nick)
    Person.filterAdult(ref) should be(List(peter, nick))
  }
  "return an empty list if no adult in the list" in {
    val ref = List(akira)
    Person.filterAdult(ref) should be(List.empty[Person])
  }
}

Here, we used a tuple to define three variables. This is a convenient way to define multiple variables. The scope of the variables is bounded by the enclosing curly brackets.
Use IntelliJ to create the filterAdult function by using the Alt+ Enter shortcut. The IDE understands that the function should be in the Person companion object and generates it for you.

We implement this method using the for comprehension Scala feature:

object Person {
  def filterAdult(persons: List[Person]) : List[Person] = {
    for {
      person <- persons
      if (person.age >= 18)
    } yield (person)
  }
}

It is a good practice to define the return type of the method, especially when this method is exposed as a public API.

The for comprehension has been used only for demonstration purposes. We can simplify it using the filter method on List. filter is part of the Scala Collections API and is available for many kinds of collections:

def filterAdult(persons: List[Person]) : List[Person] = {
  persons.filter(_.age >= 18)
}

Now, we would like to have a nice representation of the person by stating his/her name and age. The test should look like the following:

"Get a human readable representation of the person" in {
  val paul = Person(firstName = "Paul", lastName = "Smith", age = 24)
  paul.description should be("Paul Smith is 24 years old")
}

Run the test again. We will get a compilation error:

This is expected as the function doesn't exist on the Person class. To implement it, add the expected implementation by setting the cursor on the description() error in the MainSpec.scala class, hitting Alt + Enter, and selecting the create method description.
IntelliJ generates the method for you and sets the implementation to ???. Replace ??? with the expected code:

def description = s"$firstName $lastName is $age ${if (age <= 1) "year"                    else "years"} old"

By doing so, we defined a method that does not take any parameter and return a string representing Person. In order to simplify the code, we are using a string interpolation to build the string. To use string interpolation, you just have to prepend an s before the first quote. Inside the quote, you can use the wildcard $ so that we can use an external variable and use the bracket after the dollar sign to enter more code than just a variable name.

Execute the test and the result should be green:

The next step is to write a utility function that, given a list of people, returns only the adults.

For the tests, two cases are defined:

"The Person companion object" should {
  val (akira, peter, nick) = (
    Person(firstName = "Akira", lastName = "Sakura", age = 12),
    Person(firstName = "Peter", lastName = "M=C3=BCller", age = 34),
    Person(firstName = "Nick", lastName = "Tagart", age = 52)
  )
  "return a list of adult person" in {
    val ref = List(akira, peter, nick)
    Person.filterAdult(ref) should be(List(peter, nick))
  }
  "return an empty list if no adult in the list" in {
    val ref = List(akira)
    Person.filterAdult(ref) should be(List.empty[Person])
  }
}

Here, we used a tuple to define three variables. This is a convenient way to define multiple variables. The scope of the variables is bounded by the enclosing curly brackets.
Use IntelliJ to create the filterAdult function by using the Alt+ Enter shortcut. The IDE understands that the function should be in the Person companion object and generates it for you.

We implement this method using the for comprehension Scala feature:

object Person {
  def filterAdult(persons: List[Person]) : List[Person] = {
    for {
      person <- persons
      if (person.age >= 18)
    } yield (person)
  }
}

It is a good practice to define the return type of the method, especially when this method is exposed as a public API.

The for comprehension has been used only for demonstration purposes. We can simplify it using the filter method on List. filter is part of the Scala Collections API and is available for many kinds of collections:

def filterAdult(persons: List[Person]) : List[Person] = {
  persons.filter(_.age >= 18)
}

Now that all our tests are green, we can implement the main method. The implementation becomes trivial as all the code is already in the test:

object Main extends App {
  val persons = List(
    Person(firstName = "Akira", lastName = "Sakura", age = 12),
    Person(firstName = "Peter", lastName = "M=C3=BCller", age = 34),
    Person(firstName = "Nick", lastName = "Tagart", age = 52))

  val adults = Person.filterAdult(persons)
  val descriptions = adults.map(p => p.description).mkString("\n\t")
  println(s"The adults are \n\t$descriptions")
}

The first thing is to define a list of Person, so that Person.filterAdult() is used to remove all the persons, not the adults. The adults variable is a list of Person, but I would like to transform this list of Person into a list of the description of the Person. To perform this operation, the map function of the collection is used. The map function transforms each element of the list by applying the function in the parameter.

The notation inside the map() function defines an anonymous function that takes p as the parameter. The body of the function is p.description. This notation is commonly used whenever a function takes another function as an argument.

Once we have a list of descriptions, we create a string with the mkString() function. It concatenates all the elements of the list using the special character \n\t, which are respectively the carriage return and the tab character.

Finally, we perform the side effect, which is the print on the console. To print in the console, the println alias is used. It is a syntactic sugar for System.out.println.

We have finished the first chapter, and you should now have the basics to start a project on your own. We covered the installation of an IDE to code in Scala with the basic usage of the dedicated build tool named SBT. Three ways to explore Scala have been demonstrated, including the REPL to test simple Scala features, the IntelliJ worksheet to play with a small environment, and lastly a real project.

To code our first project, we used ScalaTest and the TDD methodology so that we had good code quality from the beginning. 

In the next chapter, we will write a complete program. It is a financial application that allows its users to estimate when they can retire. We will keep using the TDD technique and will further explore the Scala language, its development kit, and their best practices. 

In this chapter, we will put into practice the features of the Scala language seen in the first chapter. We will also introduce other elements of the Scala language and SDK to develop the model and logic for a retirement calculator. This calculator will help people work out how long and how much to save to have a comfortable retirement.

We will use the test-driven development (TDD) technique to develop the different functions. I encourage you to try writing the body of the functions yourself before looking at the solution. Also, it would be better to retype the code rather than copy/pasting it. You will remember it more and will have a sense of what it feels like to use IntelliJ's completion and editor. Do abuse the autocompletion with Ctrl + spacebar. You will not only type faster, but you will also discover what functions are available in a given class.

You are going to get a strong foundation for building more complex applications using the Scala language.

In this chapter, we will cover the following topics:

• Calculating the future capital
• Calculating when you can retire
• Using market rates
• Packaging the application

Using some parameters such as your net income, your expenses, your initial capital, and so on, we will create functions to calculate the following:

• Your future capital at retirement
• Your capital after a number of years in retirement
• How long you need to save to be able to retire

We will first use a fixed interest rate for these calculations. After that, we will load market data from .tsv files, then refactor the previous functions to simulate what could happen during the investment period.

The first thing you need to know when planning for retirement is how much capital you can get at your chosen retirement date. For now, we will assume that you invest your savings every month at a constant rate. To simplify things, we will ignore the effects of inflation, hence the capital calculated will be in today's money and the interest rate will be calculated as real rate = nominal interest rate - inflation rate.

We intentionally do not mention any currency in the rest of this chapter. You can consider that the amounts are in USD, EUR, or any other currency. It will not change the results as long as all the amounts are expressed in the same currency.

We want a function that behaves similarly to the FV function in Excel: it calculates the future value of an investment based on a constant interest rate. As we follow a TDD approach, the first thing to do is create a failing test:

1. Create a new Scala project called retirement_calculator. Follow the same instructions as in Chapter 1, Writing Your First Program.

1. Right-click on the directory src/main/scala and select New | Package. Name it retcalc.
2. Right-click on the new package and select New | Scala class. Name it RetCalcSpec.
3. Enter the following code:

package retcalc

import org.scalactic.{Equality, TolerantNumerics, TypeCheckedTripleEquals}
import org.scalatest.{Matchers, WordSpec}

class RetCalcSpec extends WordSpec with Matchers with TypeCheckedTripleEquals {

  implicit val doubleEquality: Equality[Double] = 
    TolerantNumerics.tolerantDoubleEquality(0.0001)

  "RetCalc.futureCapital" should {
    "calculate the amount of savings I will have in n months" in {
      val actual = RetCalc.futureCapital(
        interestRate = 0.04 / 12, nbOfMonths = 25 * 12, 
        netIncome = 3000, currentExpenses = 2000, 
        initialCapital = 10000)
      val expected = 541267.1990
      actual should ===(expected)
  }
}

As seen in Chapter 1, Writing Your First Program, in the section Creating my first project, we used the WordSpec ScalaTest style. We also used a handy feature called TypeCheckedTripleEquals. It provides a powerful assertion, should =3D=3D=3D, that ensures at compile time that both sides of the equality have the same type. The default ScalaTest assertion should verifies the type equality at runtime. We encourage you to always use should =3D=3D=3D, as it will save a lot of time when refactoring code.

Besides, it lets us use a certain amount of tolerance when comparing double values. Consider the following declaration:

implicit val doubleEquality: Equality[Double] =
  TolerantNumerics.tolerantDoubleEquality(0.0001)

It will let a double1 should =3D=3D=3D (double2) assertion pass if the absolute difference between double1 and double2 is lower than 0.0001. This allows us to specify expected values to only the fourth digit after the decimal point. It also avoids hitting floating point calculation issues. For instance, enter the following code in the Scala Console:

scala> val double1 = 0.01 -0.001 + 0.001
double1: Double = 0.010000000000000002

scala> double1 == 0.01
res2: Boolean = false

It can be a bit surprising, but this is a well-known problem in any language that encodes floating point numbers in binary. We could have used BigDecimal instead of Double to avoid this kind of issue, but for our purposes, we do not need the additional precision offered by BigDecimal, and BigDecimal computations are much slower.

The body of the test is quite straightforward; we call a function and expect a value. As we wrote the test first, we had to work out what would be the expected result before writing the production code. For non-trivial calculations, I generally use Excel or LibreOffice. For this function, the expected value can be obtained by using the formula =3D-FV(0.04/12,25*12,1000,10000,0). We assume that the user saves the full difference between his or her income and his/her expenses every month. Hence, the PMT parameter in the FV function is 1,000 = netIncome - currentExpenses.

We now have a failing test, but it does not compile, as the RetCalc object and its futureCapital function do not exist yet. Create a RetCalc object in a new package retcalc in src/main/scala, then select the red futureCapital call in the unit test and hit Alt + Enter to generate the function body. Fill in the names and types of the parameters. You should end up with the following code in RetCalc.scala:

package retcalc

object RetCalc {
  def futureCapital(interestRate: Double, nbOfMonths: Int, netIncome:     
  Int, currentExpenses: Int, initialCapital: Double): Double = ???
}

Open RetCalcSpec, and type Ctrl + Shift + R to compile and run it. Everything should compile and the test should fail.

We now have a failing test, so it is time to make it pass by writing the production code. If we use initialCapital = 10,000 and monthlySavings = 1,000, the computation we need to perform can be decomposed as follows:

• For month 0, before any savings, we have capital0 = initialCapital = 10,000.
• For month 1, our initial capital generated some interest. We also saved 1,000 more. We therefore have capital1 = capital0 *(1 + monthlyInterestRate) + 1,000
• For month 2, we have capital2 = capital1 *(1 + monthlyInterestRate) + 1,000

There is a mathematical formula to compute capitalN from the parameters, but we will not use it here. This formula works well for fixed interest rates, but we will use variable interest rates later in this chapter.

Here is the body of the function:

def futureCapital(interestRate: Double, nbOfMonths: Int, netIncome: Int, currentExpenses: Int, initialCapital: Double): Double = {
  val monthlySavings = netIncome - currentExpenses

  def nextCapital(accumulated: Double, month: Int): Double =
    accumulated * (1 + interestRate) + monthlySavings

  (0 until nbOfMonths).foldLeft(initialCapital)(nextCapital)
}

We first generate a collection of integers using 0 to nbOfMonths, and we then iterate through it using foldLeft. foldLeft is one of the most powerful functions in the Scala collection library. Many other functions in the collections library could be implemented just by using foldLeft, such as reverse, last, contains, sum, and so on.

In the Scala SDK, the signature of foldLeft is as follows:

def foldLeft[B](z: B)(op: (B, A) => B): B

You can see its definition in IntelliJ by pointing at it with the mouse and using cmd + left-click. This introduces some new syntax:

• [B] means that the function has a type parameter named B. When we call the function, the compiler automatically infers what B is, depending on the type of the z: B argument. In our code, the z argument is initialCapital, of type Double. Therefore, our call to foldLeft in futureCapital will behave as if the function was defined with B = Double:

def foldLeft(z: Double)(op: (Double, A) => Double): Double.

• The function has two parameter lists. Scala allows you to have many parameter lists. Each list can have one or many parameters. This does not change the behavior of the function; it is just a way of separating the concerns of each parameter list.
• op: (B, A) => B means that op must be a function that has two parameters of type B and A and returns a value of type B. Since foldLeft is a function that takes another function as an argument, we say that foldLeft is a higher order function.

If we consider a coll collection, foldLeft works as follows:

1. It creates a var acc = z accumulator then calls the op function:

acc = op(acc, coll(0)) 

1. It carries on calling op with each element of the collection:

acc = op(acc, coll(i))

1. It returns acc once it has iterated through all elements of the collection

In our futureCapital function, we pass op = nextCapital. The foldLeft will iterate through all Int between 1 and nbOfMonths, each time computing the capital using the previous capital. Note that, for now, we do not use the month parameter in nextCapital. We must declare it, though, because the op function in foldLeft must have two parameters.

You can now run the RetCalcSpec unit test again. It should pass.

In the TDD approach, it is common to refactor the code once we have passing tests. If our test coverage is good, we should not have any fear of changing the code, because any mishap should be flagged by a failing test. This is known as a Red-Green-Refactor cycle.

Change the body of futureCapital with the following code:

def futureCapital(interestRate: Double, nbOfMonths: Int, netIncome: Int, currentExpenses: Int, initialCapital: Double): Double = {
  val monthlySavings = netIncome - currentExpenses
  (0 until nbOfMonths).foldLeft(initialCapital)(
    (accumulated, _) => accumulated * (1 + interestRate) + 
     monthlySavings)
}

Here, we have inlined the nextCapital function in the foldLeft call. In Scala, we can define an anonymous function using the syntax:

(param1, param2, ..., paramN) => function body.

We saw earlier that the month parameter in nextCapital was not used. In an anonymous function, it is a good practice to name any unused parameter with _. A parameter named _ cannot be used in the function body. If you try to replace the _ character with a name, IntelliJ will underline it. If you hover the mouse over it, you will see a popup stating Declaration is never used. You can then hit Alt + Enter and choose to remove the unused element to automatically change it back to _.

Now you know how much capital you can expect at your retirement date. It turns out you can reuse the same futureCapital function, to work out how much capital will be left for your heirs.

Add the following test in RetCalcSpec, underneath the previous unit test, and run it. It should pass:

"RetCalc.futureCapital" should {
  "calculate how much savings will be left after having taken a pension 
    for n months" in {
    val actual = RetCalc.futureCapital(
      interestRate = 0.04/12, nbOfMonths = 40 * 12,
      netIncome = 0, currentExpenses = 2000, initialCapital = 
      541267.1990)
    val expected = 309867.53176
    actual should ===(expected)
  }
}

So, if you live for 40 years after your retirement date, spend the same amount every month, and don't have any other income, you will still have a significant capital left for your heirs. If the remaining capital was negative, that would have meant that you would have run out of money at some point during your retirement and it is an outcome we want to avoid.

Feel free to call the function from the Scala Console and try different values that would match more closely to your personal situation. Try different values for the interest rate and observe how you can end up with a negative capital if the rate is low.

Note that, in a production system, you would certainly add more unit tests to cover some other edge cases and make sure that the function will not crash. As we will cover error handling in Chapter 3, Handling Errors, we can assume that the test coverage of futureCapital is good enough for now.

Now that we know how to calculate the capital at retirement and after death, it would be useful to combine the two calls in a single function. This function will simulate a retirement plan in one go.

Here is the unit test you need to add to RetCalcSpec:

"RetCalc.simulatePlan" should {
  "calculate the capital at retirement and the capital after death" in {
    val (capitalAtRetirement, capitalAfterDeath) = 
    RetCalc.simulatePlan(
      interestRate = 0.04 / 12,
      nbOfMonthsSaving = 25 * 12, nbOfMonthsInRetirement = 40 * 12,
      netIncome = 3000, currentExpenses = 2000,
      initialCapital = 10000)
    capitalAtRetirement should === (541267.1990)
    capitalAfterDeath should === (309867.5316)
  }
}

Select the call to simulatePlan, and hit Alt + Enter to let IntelliJ create the function for you in RetCalc. It should have the following signature:

def simulatePlan(interestRate: Double,
                 nbOfMonthsSavings: Int, nbOfMonthsInRetirement: Int,
                 netIncome: Int, currentExpenses: Int, initialCapital: 
                 Double) : (Double, Double) = ???

Now compile the project with cmd + F9, and run RetCalcSpec. It should fail since the simulatePlan function must return two values. The simplest way of modeling the return type is to use Tuple2. In Scala, a tuple is an immutable data structure which holds several objects of different types. The number of objects contained in a tuple is fixed. It is akin to a case class, which does not have specific names for its attributes. In type theory, we say that a tuple or a case class is a product type.

Type the following in the Scala Console to get more familiar with tuples. Feel free to experiment with different types and sizes of tuples:

scala> val tuple3 = (1, "hello", 2.0)
tuple3: (Int, String, Double) = (1,hello,2.0)

scala> tuple3._1
res1: Int = 1

scala> tuple3._2
res2: String = hello

scala> val (a, b, c) = tuple3

a: Int = 1
b: String = hello
c: Double = 2.0

You can create tuples of any length up to 22, and access their elements using _1, _2, and so on. You can also declare several variables in one go for each element of the tuple.

The implementation for simulatePlan is straightforward; we call futureCapital twice with different arguments:

def simulatePlan(interestRate: Double,
                 nbOfMonthsSaving: Int, nbOfMonthsInRetirement: Int,
                 netIncome: Int, currentExpenses: Int, initialCapital: 
                  Double) : (Double, Double) = {
  val capitalAtRetirement = futureCapital(
    interestRate = interestRate, nbOfMonths = nbOfMonthsSaving,
    netIncome = netIncome, currentExpenses = currentExpenses,
    initialCapital = initialCapital)

  val capitalAfterDeath = futureCapital(
    interestRate = interestRate, nbOfMonths = nbOfMonthsInRetirement,
    netIncome = 0, currentExpenses = currentExpenses,
    initialCapital = capitalAtRetirement)

  (capitalAtRetirement, capitalAfterDeath)
}

Run RetCalcSpec again, and it should pass now. Feel free to experiment calling simulatePlan from the Scala Console with different values.

If you have tried to call simulatePlan from the Scala Console, you probably tried different values for nbOfMonths and observed the resulting capital at retirement and after death. It would be useful to have a function that finds the optimal nbOfMonths so that you have enough capital to never run out of money during your retirement.

As usual, let's start with a new unit test to clarify what we expect from this function:

"RetCalc.nbOfMonthsSaving" should {
  "calculate how long I need to save before I can retire" in {
    val actual = RetCalc.nbOfMonthsSaving(
      interestRate = 0.04 / 12, nbOfMonthsInRetirement = 40 * 12,
      netIncome = 3000, currentExpenses = 2000, initialCapital = 10000)
    val expected = 23 * 12 + 1
    actual should ===(expected)
  }
}

In this test, the expected value can be a bit difficult to figure out. One way would be to use the NPM function in Excel. Alternatively, you could call simulatePlan many times in the Scala Console, and increase nbOfMonthsSaving to gradually find out what the optimal value is.

In functional programming, we avoid mutating variables. In an imperative language, you would typically implement nbOfMonthsSaving by using a while loop. It is also possible to do so in Scala, but it is a better practice to only use immutable variables. One way of solving this problem is to use recursion:

def nbOfMonthsSaving(interestRate: Double, nbOfMonthsInRetirement: Int,
                     netIncome: Int, currentExpenses: Int, initialCapital: Double): Int = {
  def loop(months: Int): Int = {
    val (capitalAtRetirement, capitalAfterDeath) = simulatePlan(
      interestRate = interestRate,
      nbOfMonthsSaving = months, nbOfMonthsInRetirement = 
      nbOfMonthsInRetirement,
      netIncome = netIncome, currentExpenses = currentExpenses,
      initialCapital = initialCapital)

    val returnValue =
      if (capitalAfterDeath > 0.0)
        months
      else
        loop(months + 1)
    returnValue
  }
  loop(0)
}

We declare the recursive function inside the body of the function, as it is not meant to be used anywhere else. The loop function increments months by 1 until the calculated capitalAfterDeath is positive. The loop function is initiated in the body of nbMonthsSaving with months = 0. Note that IntelliJ highlights the fact that the loop function is recursive with a kind of @ sign.

Now, we can run our unit test again, and it should pass. However, we are not quite done yet. What happens if you can never reach a month that would satisfy the condition capitalAfterDeath > 0.0? Let's find out by writing another test.

Add the following tests underneath the previous one:

"RetCalc.nbOfMonthsSaving" should {
  "calculate how long I need to save before I can retire" in {...}

  "not crash if the resulting nbOfMonths is very high" in {
     val actual = RetCalc.nbOfMonthsSaving(
      interestRate = 0.01 / 12, nbOfMonthsInRetirement = 40 * 12,
      netIncome = 3000, currentExpenses = 2999, initialCapital = 0)
    val expected = 8280
    actual should ===(expected)
  }

  "not loop forever if I enter bad parameters" in pending

We will implement the not loop forever later on. It is a good practice to write pending tests as soon as you think about new edge cases or other use cases for your function. It helps to keep a direction toward the end goal, and gives some momentum=E2=80=94as soon as you have made the previous test pass, you know exactly what test you need to write next.

Run the test, and it will fail with StackOverflowError. This is because each time loop is called recursively, local variables are saved onto the JVM stack. The size of the stack is quite small, and as we can see, it is quite easy to fill it up. Fortunately, there is a mechanism in the Scala compiler to automatically transform tail-recursive calls into a while loop. We say that a recursive call (the call to the loop function inside the loop function) is tail-recursive when it is the last instruction of the function.

We can easily change our previous code to make it tail-recursive. Select returnValue, and hit cmd + O to inline the variable. The body of the loop function should look like this:

@tailrec
def loop(months: Int): Int = {
  val (capitalAtRetirement, capitalAfterDeath) = simulatePlan(
    interestRate = interestRate,
    nbOfMonthsSaving = months, nbOfMonthsInRetirement = 
    nbOfMonthsInRetirement,
    netIncome = netIncome, currentExpenses = currentExpenses,
    initialCapital = initialCapital)

  if (capitalAfterDeath > 0.0)
    months
  else
    loop(months + 1)

IntelliJ changed the small symbol in the editor's margin to highlight the fact that our function is now tail-recursive. Run the test again and it should pass. It is a good practice to also put an annotation @tailrec before the function definition. This tells the compiler that it must verify that the function is indeed tail-recursive. If you annotate a @tailrec function that is not tail-recursive, the compiler will raise an error.

We are not quite done yet because our function might loop indefinitely. Imagine that you always spend more than what you earn. You will never be able to save enough to retire, even if you live a million years! Here is a unit test highlighting this:

"RetCalc.nbOfMonthsSaving" should {
  "calculate how long I need to save before I can retire" in {...}

  "not crash if the resulting nbOfMonths is very high" in {...}

  "not loop forever if I enter bad parameters" in {
    val actual = RetCalc.nbOfMonthsSavingV2(
      interestRate = 0.04 / 12, nbOfMonthsInRetirement = 40 * 12,
      netIncome = 1000, currentExpenses = 2000, initialCapital = 10000)
    actual should === (Int.MaxValue)
  }
}

We decided to use a special value Int.MaxValue to indicate that nbOfMonths is infinite. This is not very pretty, but we will see in the next chapter how we can model this better with Option or Either. This is good enough for now.

To make the test pass, we just need to add an if statement:

def nbOfMonthsSaving(interestRate: Double, nbOfMonthsInRetirement: Int,
                     netIncome: Int, currentExpenses: Int, initialCapital: Double): Int = {
  @tailrec
  def loop(nbOfMonthsSaving: Int): Int = {...}

  if (netIncome > currentExpenses)
    loop(0)
  else
    Int.MaxValue
}

In our calculations, we have always assumed that the interest rate of return was constant, but the reality is more complex. It would be more accurate to use real rates from market data to gain more confidence with our retirement plan. For this, we first need to change our code to be able to perform the same calculations using variable interest rates. Then, we will load real market data to simulate regular investments in a fund by tracking the S & P 500 index.

In order to support variable rates, we need to change the signature of all functions that accept interestRate: Double. Instead of a double, we need a type that can represent either a constant rate or a sequence of rates.

Considering two types A and B, we previously saw how to define a type that can hold a value of type A and a value of type B. This is a product type, and we can define it using a tuple, such as ab: (A, B), or a case class, such as case class MyProduct(a: A, b: B).

On the other hand, a type that can hold either A or B is a sum type, and in Scala, we declare it using a sealed trait inheritance:

sealed trait Shape
case class Circle(diameter: Double) extends Shape
case class Rectangle(width: Double, height: Double) extends Shape

An Algebraic Data Type (ADT) is a type that composes sum types and product types to define a data structure. In the preceding code, we defined a Shape ADT, which composes a sum type (a Shape can be a Circle or a Rectangle), with a product type Rectangle (a Rectangle holds a width and a height).

The sealed keyword indicates that all subclasses of the trait must be declared in the same .scala file. If you attempt to declare a class that extends a sealed trait in another file, the compiler will reject it. This is used to guarantee that our inheritance tree is complete, and as we will see later on, it has interesting benefits when it comes to using pattern matching.

Going back to our problem, we can define a Returns ADT as follows. Create a new Scala class in the retcalc package in src/main/scala:

package retcalc

sealed trait Returns
case class FixedReturns(annualRate: Double) extends Returns
case class VariableReturns(returns: Vector[VariableReturn]) extends Returns
case class VariableReturn(monthId: String, monthlyRate: Double)

For VariableReturn, we keep the monthly interest rate and an identifier monthId that will have the form 2017.02, for February 2017. I recommend that you use Vector whenever you need to model a sequence of elements. Vector is faster than List for appending/inserting elements or accessing an element by index.

When we have VariableReturns over a long period, for instance, 1900 to 2017, it can be interesting to use a smaller period to simulate what would happen if the historical returns in a smaller period, say 50 years, would be repeated.

We are going to create a method in the VariableReturns class that will keep only the returns contained in a specific period. Here is the unit test in ReturnsSpec.scala:

"VariableReturns.fromUntil" should {
  "keep only a window of the returns" in {
    val variableReturns = VariableReturns(Vector.tabulate(12) { i =>
      val d = (i + 1).toDouble
      VariableReturn(f"2017.$d%02.0f", d)
    })

    variableReturns.fromUntil("2017.07", "2017.09").returns should ===
    (Vector(
      VariableReturn("2017.07", 7.0),
      VariableReturn("2017.08", 8.0)
    ))

    variableReturns.fromUntil("2017.10", "2018.01").returns should ===
    (Vector(
      VariableReturn("2017.10", 10.0),
      VariableReturn("2017.11", 11.0),
      VariableReturn("2017.12", 12.0)
    ))
  }
}

First, we generate a sequence of returns and assign them to variableReturns using the function Vector.tabulate. It generates 12 elements, and each element is produced by an anonymous function, taking a parameter i that will go from 0 to 11. In the call to the VariableReturn constructor, for the monthId argument, we use the f interpolator to generate a string in the form 2017.01 when d = 1, 2017.02 when d = 2, and so on.

The function fromUntil that we are specifying will return a VariableReturns type that contains a specific window inside the original returns. For now, we assume that the arguments passed to fromUntil are valid months that are present in variableReturns. Ideally, we should add unit tests to specify what should happen if they are not.

Here is the implementation in Returns.scala:

case class VariableReturns(returns: Vector[VariableReturn]) extends Returns {
  def fromUntil(monthIdFrom: String, monthIdUntil: String): 
    VariableReturns =
    VariableReturns(
      returns
        .dropWhile(_.monthId != monthIdFrom)
        .takeWhile(_.monthId != monthIdUntil))
}

We use the higher order function dropWhile to drop elements until we reach the condition monthId == monthIdFrom. Then, we call takeWhile on the resulting collection to keep all elements until monthId == monthIdUntil. This will return a collection that keeps only the elements in a window that starts at monthIdFrom and ends just before monthIdUntil.

Run ReturnsSpec, and it should pass.

Now that we have a way of expressing variable returns, we need to change our futureCapital function to accept a Returns type instead of a monthly interest rate of type Double. Change the tests first:

"RetCalc.futureCapital" should {
    "calculate the amount of savings I will have in n months" in {
      // Excel =-FV(0.04/12,25*12,1000,10000,0)
      val actual = RetCalc.futureCapital(FixedReturns(0.04), 
        nbOfMonths = 25 * 12, netIncome = 3000, 
        currentExpenses = 2000, initialCapital = 10000).right.value
      val expected = 541267.1990
      actual should ===(expected)
    }

    "calculate how much savings will be left after having taken a 
     pension for n months" in {
      val actual = RetCalc.futureCapital(FixedReturns(0.04), 
        nbOfMonths = 40 * 12, netIncome = 0, currentExpenses = 2000, 
        initialCapital = 541267.198962).right.value
      val expected = 309867.5316
      actual should ===(expected)
    }
  }

Then, change the futureCapital function in RetCalc as follows:

def futureCapital(returns: Returns, nbOfMonths: Int, netIncome: Int, currentExpenses: Int,
                  initialCapital: Double): Double = {
  val monthlySavings = netIncome - currentExpenses
  (0 until nbOfMonths).foldLeft(initialCapital) {
    case (accumulated, month) =>
      accumulated * (1 + Returns.monthlyRate(returns, month)) + 
      monthlySavings
  }
}

Here, instead of just using the interestRate in the formula, we introduced a new function called Returns.monthlyRate which we must now create. As we follow a rather strict TDD approach, we will only create its signature first, then write the unit test, and finally implement it.

Write the function signature in Returns.scala:

object Returns {
  def monthlyRate(returns: Returns, month: Int): Double = ???
}

Create a new unit test ReturnsSpec in the retcalc package in src/test/scala:

class ReturnsSpec extends WordSpec with Matchers with TypeCheckedTripleEquals {

  implicit val doubleEquality: Equality[Double] =
    TolerantNumerics.tolerantDoubleEquality(0.0001)

  "Returns.monthlyRate" should {
    "return a fixed rate for a FixedReturn" in {
      Returns.monthlyRate(FixedReturns(0.04), 0) should ===(0.04 / 12)
      Returns.monthlyRate(FixedReturns(0.04), 10) should ===(0.04 / 12)
    }

    val variableReturns = VariableReturns(Vector(
      VariableReturn("2000.01", 0.1), 
      VariableReturn("2000.02", 0.2)))
    "return the nth rate for VariableReturn" in {
      Returns.monthlyRate(variableReturns, 0) should ===(0.1)
      Returns.monthlyRate(variableReturns, 1) should ===(0.2)
    }

    "roll over from the first rate if n > length" in {
      Returns.monthlyRate(variableReturns, 2) should ===(0.1)
      Returns.monthlyRate(variableReturns, 3) should ===(0.2)
      Returns.monthlyRate(variableReturns, 4) should ===(0.1)
    }
  }

These tests act as a specification for our monthlyRate function. For VariableRate, the monthlyRate must return the n^th rate stored in the returned Vector. If n is greater than the number of rates, we decide that monthlyRate should go back to the beginning of Vector, as if the history of our variable returns would repeat itself infinitely. We could have made a different choice here, for instance, we could have taken a mirror of the returns, or we could have just returned some error if we reached the end. To implement this rotation, we are taking the month value and applying the modulo ( % in Scala ) of the length of the vector.

The implementation introduces a new element of syntax, called pattern matching:

def monthlyRate(returns: Returns, month: Int): Double = returns match {
  case FixedReturns(r) => r / 12
  case VariableReturns(rs) => rs(month % rs.length).monthlyRate
}

You can now run ReturnsSpec, and all tests should pass. Pattern matching allows you to deconstruct an ADT and evaluate some expression when it matches one of the patterns. You can also assign variables along the way and use them in the expression. In the preceding example, case FixedReturns(r) => r/12 can be interpreted as "if the variable returns is of type FixedReturns, assign r = returns.annualRate, and return the result of the expression r/12".

This is a simple example, but you can use much more complicated patterns. This feature is very powerful, and can often replace lots of if/else expressions. You can try some more complex patterns in the Scala Console:

scala> Vector(1, 2, 3, 4) match {
  case head +: second +: tail => tail
}
res0: scala.collection.immutable.Vector[Int] = Vector(3, 4)

scala> Vector(1, 2, 3, 4) match {
  case head +: second +: tail => second
}

scala> ("0", 1, (2.0, 3.0)) match {
  case ("0", int, (d0, d1)) => d0 + d1
}
res2: Double = 5.0

scala> "hello" match {
  case "hello" | "world" => 1
  case "hello world" => 2
}
res3: Int = 1

scala> def present(p: Person): String = p match {
  case Person(name, age) if age < 18 => s"$name is a child"
  case p => s"${p.name} is an adult" 
}
present: (p: Person)String

It is a good practice to exhaustively match all possible patterns for your value. Otherwise, if no pattern matches the value, Scala will raise a runtime exception, and it might crash your program. However, when you use sealed traits, the compiler is aware of all the possible classes for a trait and will issue a warning if you do not match all cases.

In Returns.scala, try to comment out this line with cmd + /:

  def monthlyRate(returns: Returns, month: Int): Double = returns match {
//    case FixedReturns(r) => r / 12
    case VariableReturns(rs) => rs(month % rs.length).monthlyRate
  }

Recompile the project with cmd + F9. The compiler will warn you that you are doing something wrong:

Warning:(27, 59) match may not be exhaustive.
It would fail on the following input: FixedReturns(_)
  def monthlyRate(returns: Returns, month: Int): Double = returns match {

If you then try to remove the sealed keyword and recompile, the compiler will not issue any warning.

We now have a good grasp of how to use pattern matching. Keep the sealed keyword, revert the comment in monthlyRate, and run ReturnsSpec to make sure everything is green again.

If you are coming from an object-oriented language, you might wonder why we did not implement monthlyRate using an abstract method with implementations in FixedRate and VariableRate. This is perfectly feasible in Scala, and some people might prefer this design choice.

However, as I am an advocate of a functional programming style, I prefer using pure functions in objects:

• They are easier to reason about, as the whole dispatching logic is in one place.
• They can be moved to other objects easily, which facilitates refactoring.
• They have a more limited scope. In class methods, you always have all the attributes of the class in scope. In a function, you only have the parameters of the function. This helps unit testing and readability, as you know that the function cannot use anything else but its parameters. Also, it can avoid side effects when the class has mutable attributes.
• Sometimes in object-oriented design, when a method manipulates two objects, A and B, it is not clear if the method should be in class A or class B.

As we changed the signature of futureCapital, we also need to change the callers of that function. The only caller is simulatePlan. Before introducing variable rates, the implementation was straightforward: we just had to call futureCapital for the accumulation and decumulation phases with the same fixed rate argument. However, with variable rate, we must make sure that the decumulation phase uses the rates that follow the rates of the accumulation phase.

For instance, consider that you started saving in 1950, and retired in 1975. For the accumulation phase, you need to use the returns from 1950 to 1975, and for the decumulation, you must use the returns from 1975. We created a new unit test to make sure that we are using different returns for the two phases:

val params = RetCalcParams(
  nbOfMonthsInRetirement = 40 * 12,
  netIncome = 3000,
  currentExpenses = 2000,
  initialCapital = 10000)

"RetCalc.simulatePlan" should {
  "calculate the capital at retirement and the capital after death" in {
    val (capitalAtRetirement, capitalAfterDeath) = 
    RetCalc.simulatePlan(
      returns = FixedReturns(0.04), params, nbOfMonthsSavings = 25*12)

    capitalAtRetirement should === (541267.1990)
    capitalAfterDeath should === (309867.5316)
  }

  "use different returns for capitalisation and drawdown" in {
    val nbOfMonthsSavings = 25 * 12
    val returns = VariableReturns(
      Vector.tabulate(nbOfMonthsSavings + 
        params.nbOfMonthsInRetirement)(i =>
        if (i < nbOfMonthsSavings)
          VariableReturn(i.toString, 0.04 / 12)
        else
          VariableReturn(i.toString, 0.03 / 12)))
    val (capitalAtRetirement, capitalAfterDeath) =
      RetCalc.simulatePlan(returns, params, nbOfMonthsSavings)
    capitalAtRetirement should ===(541267.1990)
    capitalAfterDeath should ===(-57737.7227)
  }
}

Since simulatePlan has quite a lot of parameters apart from the returns parameter, we decided to put them in a case class called RetCalcParams. This way, we are able to reuse the same parameters for different unit tests. We will also be able to reuse it in nbMonthsSaving. As seen previously, we use the function tabulate to generate values for our variable returns.

The expected value for capitalAtRetirement can be obtained with Excel by using -FV(0.04/12, 25*12, 1000, 10000). The expected value for capitalAfterDeath can be obtained by using -FV(0.03/12, 40*12, -2000, 541267.20).

Here is the implementation in RetCalc:

case class RetCalcParams(nbOfMonthsInRetirement: Int,
                         netIncome: Int,
                         currentExpenses: Int,
                         initialCapital: Double)

object RetCalc {
  def simulatePlan(returns: Returns, params: RetCalcParams, 
  nbOfMonthsSavings: Int)
  : (Double, Double) = {
    import params._
    val capitalAtRetirement = futureCapital(
      returns = returns,
      nbOfMonths = nbOfMonthsSavings,
      netIncome = netIncome, currentExpenses = currentExpenses,
      initialCapital = initialCapital)

    val capitalAfterDeath = futureCapital(
      returns = OffsetReturns(returns, nbOfMonthsSavings),
      nbOfMonths = nbOfMonthsInRetirement,
      netIncome = 0, currentExpenses = currentExpenses,
      initialCapital = capitalAtRetirement)

    (capitalAtRetirement, capitalAfterDeath)
  }

The first line, import params._, brings all the parameters of RetCalcParams into scope. This way, you can directly use, for instance, netIncome without having to prefix it with params.netIncome . In Scala, you can not only import classes from a package, but also functions or values from an object.

In the second call to futureCapital, we introduce a new subclass called OffsetReturns, which will shift the starting month. We need to write a new unit test for it in ReturnsSpec:

"Returns.monthlyReturn" should {
  "return a fixed rate for a FixedReturn" in {...}

  val variableReturns = VariableReturns(
    Vector(VariableReturn("2000.01", 0.1), VariableReturn("2000.02", 0.2)))

  "return the nth rate for VariableReturn" in {...}

  "return an error if n > length" in {...}

  "return the n+offset th rate for OffsetReturn" in {
      val returns = OffsetReturns(variableReturns, 1)
      Returns.monthlyRate(returns, 0).right.value should ===(0.2)
    }
}

And the corresponding implementation in Returns.scala is as follows:

sealed trait Returns
case class FixedReturns(annualRate: Double) extends Returns
case class VariableReturn(monthId: String, monthlyRate: Double)
case class OffsetReturns(orig: Returns, offset: Int) extends Returns

object Returns {
  def monthlyRate(returns: Returns, month: Int): Double = returns match {
    case FixedReturns(r) => r / 12
    case VariableReturns(rs) => rs(month % rs.length).monthlyRate
    case OffsetReturns(rs, offset) => monthlyRate(rs, month + offset)
  }
}

For an offset return, we call monthlyRate recursively and add the offset to the requested month.

Now, you can compile everything with cmd + F9 and rerun the unit tests. They should all pass.

In order to calculate the real monthly returns of our investments in a fund tracking the S & P 500, we are going to load a tab-separated file containing the S & P 500 prices and dividends, and another file containing the consumer price index. This will let us calculate a real rate of return, stripped out of inflation.

First, copy sp500_2017.tsv from https://github.com/PacktPublishing/Scala-Programming-Projects/blob/master/Chapter02/retirement-calculator/src/main/resources/sp500.tsv to src/test/resources. Then, create a new unit test called EquityDataSpec in the retcalc package. If you retype this example, try the column selection mode (Alt + Shift + Insert). Copy the content of the .tsv file in the test, then select the first column with Shift + Down 13 times, and then type EquityData(". Finally, edit the rest of the lines using the arrow keys, delete, comma, and so on:

package retcalc

import org.scalatest.{Matchers, WordSpec}

class EquityDataSpec extends WordSpec with Matchers {
  "EquityData.fromResource" should {
    "load market data from a tsv file" in {
      val data = EquityData.fromResource("sp500_2017.tsv")
      data should ===(Vector(
        EquityData("2016.09", 2157.69, 45.03),
        EquityData("2016.10", 2143.02, 45.25),
        EquityData("2016.11", 2164.99, 45.48),
        EquityData("2016.12", 2246.63, 45.7),
        EquityData("2017.01", 2275.12, 45.93),
        EquityData("2017.02", 2329.91, 46.15),
        EquityData("2017.03", 2366.82, 46.38),
        EquityData("2017.04", 2359.31, 46.66),
        EquityData("2017.05", 2395.35, 46.94),
        EquityData("2017.06", 2433.99, 47.22),
        EquityData("2017.07", 2454.10, 47.54),
        EquityData("2017.08", 2456.22, 47.85),
        EquityData("2017.09", 2492.84, 48.17)
      ))
    }
  }

  "EquityData.monthlyDividend" should {
    "return a monthly dividend" in {
      EquityData("2016.09", 2157.69, 45.03).monthlyDividend should === 
      (45.03 / 12)
    }
  }
}

The first lines of sp500_2017.tsv look like this:

month   SP500  dividend
2016.09    2157.69    45.03
2016.10    2143.02    45.25
2016.11    2164.99    45.48

Our implementation must drop the first line which contains the headers, then for each line, split and create a new instance of EquityData:

package retcalc

import scala.io.Source

case class EquityData(monthId: String, value: Double, annualDividend: Double) {
  val monthlyDividend: Double = annualDividend / 12
}

object EquityData {
  def fromResource(resource: String): Vector[EquityData] =
    Source.fromResource(resource).getLines().drop(1).map { line =>
      val fields = line.split("\t")
      EquityData(
        monthId = fields(0), 
        value = fields(1).toDouble, 
        annualDividend = fields(2).toDouble)
    }.toVector
}

This code is quite compact, and you might lose a sense of what types are returned by intermediate calls. In IntelliJ, you can select a portion of code and hit Alt + =3D to show the inferred type of the expression.

We first load the .tsv file using scala.io.Source.fromResource. This takes the name of a file located in a resource folder and returns a Source object. It can be in src/test/resources or src/main/resources. When you run a test, both folders will be searched. If you run the production code, only the files in src/main/resources will be accessible.

getLines returns Iterator[String]. An iterator is a mutable data structure that allows you to iterate over a sequence of elements. It provides many functions that are common to other collections. Here, we drop the first line, which contains the header, and transforms each line using an anonymous function passed to map.

The anonymous function takes line of type string, transforms it into Array[String] using split, and instantiates a new EquityData object.

Finally, we convert the resulting Iterator[EquityData] into Vector[EquityData] using .toVector. This step is very important: we convert the mutable, unsafe, iterator into an immutable, safe Vector. Public functions should, in general, not accept or return mutable data structures:

• It makes the code harder to reason about, as you have to remember the state the mutable structure is in.
• The program will behave differently depending on the order/repetition of the function calls. In the case of an iterator, it can be iterated only once. If you need to iterate again, you won't get any data:

scala> val iterator = (1 to 3).iterator
iterator: Iterator[Int] = non-empty iterator

scala> iterator foreach println
1
2
3

scala> iterator foreach println

scala> 

Now that we can load some equity data, we need to load inflation data so that we're able to compute inflation-adjusted returns. It is very similar to the loading of equity data.

First, copy cpi_2017.tsv from https://github.com/PacktPublishing/Scala-Programming-Projects/blob/master/Chapter02/retirement-calculator/src/main/resources/cpi.tsv to src/test/resources. Then, create a new unit test called InflationDataSpec in the retcalc package:

package retcalc

import org.scalatest.{Matchers, WordSpec}

class InflationDataSpec extends WordSpec with Matchers {
  "InflationData.fromResource" should {
    "load CPI data from a tsv file" in {
      val data = InflationData.fromResource("cpi_2017.tsv")
      data should ===(Vector(
        InflationData("2016.09", 241.428),
        InflationData("2016.10", 241.729),
        InflationData("2016.11", 241.353),
        InflationData("2016.12", 241.432),
        InflationData("2017.01", 242.839),
        InflationData("2017.02", 243.603),
        InflationData("2017.03", 243.801),
        InflationData("2017.04", 244.524),
        InflationData("2017.05", 244.733),
        InflationData("2017.06", 244.955),
        InflationData("2017.07", 244.786),
        InflationData("2017.08", 245.519),
        InflationData("2017.09", 246.819)
      ))
    }
  }
}

Then, create the corresponding InflationData class and companion object:

package retcalc

import scala.io.Source

case class InflationData(monthId: String, value: Double)

object InflationData {
  def fromResource(resource: String): Vector[InflationData] =
    Source.fromResource(resource).getLines().drop(1).map { line =>
      val fields = line.split("\t")
      InflationData(monthId = fields(0), value = fields(1).toDouble)
    }.toVector
}

For a given month, n, the real return is return_n - inflationRate_n, hence the following formula:

We are going to create a new function in Returns that creates VariableReturns using Vector[EquityData] and Vector[InflationData]. Add the following unit test to ReturnsSpec:

"Returns.fromEquityAndInflationData" should {
  "compute real total returns from equity and inflation data" in {
    val equities = Vector(
      EquityData("2117.01", 100.0, 10.0),
      EquityData("2117.02", 101.0, 12.0),
      EquityData("2117.03", 102.0, 12.0))

    val inflations = Vector(
      InflationData("2117.01", 100.0),
      InflationData("2117.02", 102.0),
      InflationData("2117.03", 102.0))

    val returns = Returns.fromEquityAndInflationData(equities, 
    inflations)
    returns should ===(VariableReturns(Vector(
      VariableReturn("2117.02", (101.0 + 12.0 / 12) / 100.0 - 102.0 / 
      100.0),
      VariableReturn("2117.03", (102.0 + 12.0 / 12) / 101.0 - 102.0 / 
      102.0))))
  }
}

We create two small Vector instances of EquityData and InflationData, and calculate the expected value using the preceding formula.

Here is the implementation of fromEquityAndInflationData in Returns.scala:

object Returns {
  def fromEquityAndInflationData(equities: Vector[EquityData],
    inflations: Vector[InflationData]):
      VariableReturns = {
        VariableReturns(equities.zip(inflations).sliding(2).collect {
          case (prevEquity, prevInflation) +: (equity, inflation) +:
            Vector() =>
            val inflationRate = inflation.value / prevInflation.value
            val totalReturn =
            (equity.value + equity.monthlyDividend) / prevEquity.value
            val realTotalReturn = totalReturn - inflationRate

            VariableReturn(equity.monthId, realTotalReturn)
          }.toVector)
}

Firstly, we zip the two Vectors to create a collection of tuples, (EquityData, InflationData). This operation brings our two collections together as if we were zipping a jacket. It is a good habit to play around with the Scala Console to get a sense of what it does:

scala> Vector(1,2).zip(Vector("a", "b", "c"))
res0: scala.collection.immutable.Vector[(Int, String)] = Vector((1,a), (2,b))

Note that the resulting Vector has a size that is the minimum size of the two arguments. The last element, "c", is lost, because there is nothing to zip it with!

This is a good start, as we could now iterate through a collection that can give us priceⁿ, dividendsⁿ, and inflationⁿ. But in order to calculate our formula, we also need the previous data on n-1. For this, we use sliding(2). I encourage you to read the documentation on sliding. Let's try it in the console:

scala> val it = Vector(1, 2, 3, 4).sliding(2)
it: Iterator[scala.collection.immutable.Vector[Int]] = non-empty iterator

scala> it.toVector
res0: Vector[scala.collection.immutable.Vector[Int]] = 
Vector(Vector(1, 2), Vector(2, 3), Vector(3, 4))

scala> Vector(1).sliding(2).toVector
res12: Vector[scala.collection.immutable.Vector[Int]] = Vector(Vector(1))

sliding(p) creates an Iterator which will produce collections of size p. Each collection will have a new iterated element plus all the previous p-1 elements. Notice that if the collection size n is lower than p, the produced collection will have a size of n.

Next, we iterate through the sliding collections using collect. collect is similar to map: it allows you to transform the elements of a collection, but with the added capability of filtering them. Basically, whenever you want to filter and map a collection, you can use collect instead. The filtering is performed using pattern matching. Anything that does not match any pattern is filtered out:

scala> val v = Vector(1, 2, 3)
v: scala.collection.immutable.Vector[Int] = Vector(1, 2, 3)

scala> v.filter(i => i != 2).map(_ + 1)
res15: scala.collection.immutable.Vector[Int] = Vector(2, 4)

scala> v.collect { case i if i != 2 => i + 1 }
res16: scala.collection.immutable.Vector[Int] = Vector(2, 4)

Notice that, in the preceding code, we used map(_ + 1) instead of map(i => i + 1). This is a shorthand notation for an anonymous function. Whenever you use a parameter once in your anonymous function, you can replace it with _.

Finally, we pattern match on our zipped and sliding elements using the following:

case (prevEquity, prevInflation) +: (equity, inflation) +: Vector() =>

This has the benefit of filtering out sliding elements of size 0 or 1, if we were passing equities or inflation arguments of size 0 or 1. We will not write a unit test for this edge case in this book, but I encourage you to do so as an excercise.

The rest of the function is straightforward: we use the matched variables to compute the formula and create a new VariableReturn instance. The resulting iterator is converted to Vector, and we instantiate a VariableReturns case class using it.

We have now implemented some useful building blocks, and it is time to create an executable so that end users can use our calculator with their own parameters.

We are going to build a simple executable around RetCalc.simulatePlan. It will take a list of parameters separated by spaces, and print the results on the console.

The test we are going to write integrates several components together and will use a full market data set. As such, it is not really a unit test anymore; it is an integration test. For this reason, we suffixed it with IT instead of Spec.

First, copy sp500.tsv and cpi.tsv from https://github.com/PacktPublishing/Scala-Programming-Projects/blob/master/Chapter02/retirement-calculator/src/main/resources/sp500.tsv and https://github.com/PacktPublishing/Scala-Programming-Projects/blob/master/Chapter02/retirement-calculator/src/main/resources/cpi.tsv to src/main/resources, then create a new unit test called SimulatePlanIT in src/test/scala:

package retcalc

import org.scalactic.TypeCheckedTripleEquals
import org.scalatest.{Matchers, WordSpec}

class SimulatePlanAppIT extends WordSpec with Matchers with TypeCheckedTripleEquals {
  "SimulatePlanApp.strMain" should {
    "simulate a retirement plan using market returns" in {
      val actualResult = SimulatePlanApp.strMain(
        Array("1997.09,2017.09", "25", "40", "3000", "2000", "10000"))

      val expectedResult =
        s"""
          |Capital after 25 years of savings:    499923
          |Capital after 40 years in retirement: 586435
        """.stripMargin
      actualResult should === (expectedResult)
    }
  }
}

We call a function called strMain which will return a string instead of printing it to the console. This way, we can assert on the content printed to the console. To keep things simple, we assume that the arguments are passed in a specific order. We will develop a more user-friendly interface in the next chapter. The arguments are as follows:

1. A period that we will use in the variables returns, separated by a comma
2. The number of years of savings
3. The number of years in retirement
4. Income
5. Expenses
6. Initial capital

The expected value is a string that we define using triple quotes. In Scala, a string enclosed in triple quotes lets you enter special characters such as a quote or newline. It is very convenient to enter multiline strings while keeping a good indentation. The | characters allow you to mark the beginning of each line, and the .stripMargin function removes the white spaces before the |, as well as the | itself in order. In IntelliJ, when you type """ and then hit Enter, it automatically adds the | and .stripMargin after the closing triple quote.

The implementation calls the different functions we implemented earlier. Notice that IntelliJ can autocomplete the name of the files using Ctrl + spacebar, for instance, after EquityData.fromResource("Create a new object SimulatePlanApp in the package retcalc:

package retcalc

object SimulatePlanApp extends App {
  println(strMain(args))

  def strMain(args: Array[String]): String = {
    val (from +: until +: Nil) = args(0).split(",").toList
    val nbOfYearsSaving = args(1).toInt
    val nbOfYearsInRetirement = args(2).toInt

    val allReturns = Returns.fromEquityAndInflationData(
      equities = EquityData.fromResource("sp500.tsv"),
      inflations = InflationData.fromResource("cpi.tsv"))
    val (capitalAtRetirement, capitalAfterDeath) = 
    RetCalc.simulatePlan(
      returns = allReturns.fromUntil(from, until),
      params = RetCalcParams(
        nbOfMonthsInRetirement = nbOfYearsInRetirement * 12,
        netIncome = args(3).toInt,
        currentExpenses = args(4).toInt,
        initialCapital = args(5).toInt),
      nbOfMonthsSavings = nbOfYearsSaving * 12)

    s"""
       |Capital after $nbOfYearsSaving years of savings:    
    ${capitalAtRetirement.round}
       |Capital after $nbOfYearsInRetirement years in retirement: 
    ${capitalAfterDeath.round}
        """.stripMargin
  }
}

The only code executed when we run our executable will be println(strMain(args)). It is a good practice to keep this code as short as possible because it is not covered by any test. Our function strMain is covered, so we are fairly sure there won't be any unexpected behavior from a single println. args is an Array[String] containing all the arguments passed to the executable.

The first line of strMain uses a pattern matching on List to assign from and until. The variables will be assigned only if the split first argument, in our test "1997.09,2017.09", is a List of two elements.

Then, we load the equity and inflation data from our .tsv files. They contain data from 1900.01 until 2017.09. We then call Returns.fromEquityAndInflationData to compute the real returns.

After having assigned the returns to allReturns, we call simulatePlan with the right arguments. The returns are filtered for a specific period using from and until. Finally, we return String using a string interpolation and triple quotes.

This implementation is the first draft and is quite brittle. It will indeed crash with a horrible ArrayIndexOutOfBoundsException if we do not pass enough parameters to our executable, or with a NumberFormatException if some strings cannot be converted to Int or Double. We will see in the next chapter how we can handle these error cases gracefully, but for now, our calculator does the job as long as we feed it with the right arguments.

You can now run SimulatePlanIT, and it should pass.

Since we built an application, we can also run it as such. Move your cursor to SimulatePlanApp, and hit Ctrl + Shift + R. The app should run and crash with an exception because we did not pass any arguments. Click on the launcher for SimulatePlanApp (underneath the Build menu), then click Edit Configurations. Put the following in program arguments:

1997.09,2017.09 25 40 3000 2000 10000

Then, click OK, and run SimulatePlanApp again. It should print the same content as what we had in our unit test. You can try calling the application with different parameters and observe the resulting calculated capitals.

So far so good, but what if we want to send this application to uncle Bob so that he can plan for his retirement too? It would not be very convenient to ask him to download IntelliJ or SBT. We are going to package our application in a .jar file so that we can run it with a single command.

SBT provides a package task that can create a .jar file, but this file will not contain the dependencies. In order to package our own classes as well as the classes coming from the dependent libraries, we are going to use the sbt-assembly plugin. Create a new file called project/assembly.sbt containing the following:

addSbtPlugin("com.eed3si9n" % "sbt-assembly" % "0.14.6")

Then, edit build.sbt to define the name of our main class:

name := "retirement_calculator"

version := "0.1"

scalaVersion := "2.12.4"

libraryDependencies += "org.scalatest" %% "scalatest" % "3.0.4" % "test"

mainClass in Compile := Some("retcalc.SimulatePlanApp")

Click on the SBT tab on the top-right and then on the Refresh button. Then, expand the project and double-click on the assembly task:

The assembly task will compile all the classes, run all the tests, and if they all pass, package a fat JAR. You should see an output similar to this at the bottom of the SBT console:

[info] Checking every *.class/*.jar file's SHA-1.
[info] Merging files...
[warn] Merging 'META-INF/MANIFEST.MF' with strategy 'discard'
[warn] Strategy 'discard' was applied to a file
[info] SHA-1: 7b7710bf370159c549a11754bf66302a76c209b2
[info] Packaging /home/mikael/projects/scala_fundamentals/retirement_calculator/target/scala-2.12/retirement_calculator-assembly-0.1.jar ...
[info] Done packaging.
[success] Total time: 11 s, completed 14-Jan-2018 12:23:39

Copy the location of the .jar file in your clipboard. Now, you can use a Unix terminal or a Windows command prompt and run the application as follows:

$ java -jar  1997.09,2017.09 25 40 3000 2000 10000

Capital after 25 years of savings: 499923
Capital after 40 years in retirement: 586435

It is now easier to try different parameters. It is interesting to see that some periods are much more lucrative than others:

$ java -jar  2000.01,2010.01 25 40 3000 2000 10000

Capital after 25 years of savings:    225209
Capital after 40 years in retirement: -510074
        
$ java -jar  1950.01,1960.01 25 40 3000 2000 10000

Capital after 25 years of savings:    4505196
Capital after 40 years in retirement: 2077953853

We have covered how to create a small project in Scala from scratch to packaging. We used TDD along the way so that it is guaranteed that our code was well-designed and robust. It gives us confidence when we refactor code: as long as all tests pass, we know that our code stills works. We modeled our domain with immutable data structures and processed them using pure functions that have no side effects.

We used some basic features of the language that are used in most projects, and you should now be familiar with enough building blocks to implement a wide variety of projects.

As a further exercise, you could enhance this calculator with one or many of these features:

• Create an app for the function RetCalc.nbOfMonthsSaving, which calculates how long you need to save before you can retire.
• Create a function called RetCalc.annualizedTotalReturn, which calculates the geometric average of a sequence of returns. See https://www.investopedia.com/terms/a/annualized-total-return.asp for more details.
• Create a function called monthlyPension, which calculates how much you will get in retirement if you save a given amount every month for a given number of months.
• Incorporate other streams of income. Maybe you will get a state pension after a number of years, or you might get an inheritance.
• Load a different index, such as STOXX Europe 600, MSCI World Index, and so on.
• Most people do not invest all their savings in the stock market, but wisely diversify with bonds, that is, typically 60% stocks, 40% bonds. You could add a new function in Returns.scala to calculate the returns of a mixed portfolio.
• We observed that some periods have much higher returns than others. As it is difficult to predict the future, you could run multiple simulations using different periods, and calculate a probability of success.

In the next chapter, we will improve our calculator further by handling errors in a functional way.

In this chapter, we will continue working on the retirement calculator that we implemented in Chapter 2, Developing a Retirement Calculator. Our calculator worked correctly as long as we passed the right arguments, but would fail badly with a horrible stack trace if any of the parameters were wrong. Our program only worked for what we call the happy path.

The reality of writing production software is that all kinds of error scenarios can occur. Some of them are recoverable, some of them must be presented to the user in an attractive way, and, for some hardware-related errors, we might need to let the program crash.

In this chapter, we will introduce exception handling, explain what referential transparency is, and try to convince you that exceptions are not the best way to deal with errors. Then, we will explain how to use functional programming constructs to effectively handle the possibility of an error.

In each section, we will briefly introduce a new concept, and then use it in a Scala worksheet to get a sense of how to use it. After that, we will apply this new knowledge to improve the retirement calculator.

In this chapter, we will look at the following topics:

• Using exceptions when necessary
• Understanding referential transparency
• Using Option to represent optional values
• Using Either to handle errors sequentially
• Using Validated to handle errors in parallel

If you have not completed Chapter 2, Developing a Retirement Calculator, then you can check out the retirement calculator project at GitHub. If you are not already familiar with Git, I would advise that you read the documents at https://guides.github.com/introduction/git-handbook/ first.

To begin the setup, go through the following steps:

1. Create an account at https://github.com/ if you do not have one already.
2. Go to the retirement calculator project at https://github.com/PacktPublishing/Scala-Programming-Projects. Click on Fork in the top-right corner to fork the project into your account.
3. Once the project is forked, click on Clone or download, and copy the URL into the clipboard.
4. In IntelliJ, go to File | New | Project from Version Control | GitHub and make the following edits:
   • Git repository URL: Paste the URL of your forked repository
   • Parent directory: Choose a location
   • Directory name: Keep retirement_calculator
   • Click on Clone
5. The project should be imported in IntelliJ. Click on git: master in the bottom-right of the screen and select Remote branches | origin/chapter2 | Checkout as new local branch. Name the new branch chapter3_yourusername to distinguish it from the final solution, which is in the origin/chapter3 branch.
6. Build the project with Ctrl + F9. Everything should compile.

Exceptions are one of the mechanisms that we can use in Scala to handle error scenarios. It consists of two statements:

• The throw exceptionObject statement stops the current function and passes the exception up to the caller.
• The try { myFunc() } catch { case pattern1 => recoverExpr1 } statement catches any exception thrown by myFunc() if the exception matches one of the patterns inside the catch block:
• If an exception is thrown by myFunc, but no pattern matches the exception, the function stops, and the exception is passed up to the caller again. If there is no try...catch block in the call chain that can catch the exception, the whole program stops.
• If an exception is thrown by myFunc, and the pattern1 pattern matches the exception, the try...catch block will return the recoverExpr1 expression at the right of the arrow.
• If no exception is thrown, the try...catch block returns the result returned by myFunc().

This mechanism comes from Java, and since the Scala SDK sits on top of the Java SDK, many function calls to the SDK can throw exceptions. If you are familiar with Java, the Scala exception mechanism differs slightly. Exceptions in Scala are always unchecked, which means that the compiler will never force you to catch an exception or declare that a function can throw an exception.

The following is a code snippet that demonstrates how exceptions can be thrown. You can paste it in the Scala console or in a Scala worksheet:

case class Person(name: String, age: Int)
case class AgeNegativeException(message: String) extends Exception(message)

def createPerson(description: String): Person = {
  val split = description.split(" ")
  val age = split(1).toInt
  if (age < 0)
    throw AgeNegativeException(s"age: $age should be > 0")
  else
    Person(split(0), age)

The createPerson function creates the Person object if the string passed in an argument is correct, but throws different types of exceptions if it is not. In the preceding code, we also implemented our own AgeNegativeException isntance, which is thrown if the age passed in the string is negative, as shown in the following code:

scala> createPerson("John 25")
res0: Person = Person(John,25)

scala> createPerson("John25")
java.lang.ArrayIndexOutOfBoundsException: 1
  at .createPerson(:17)
  ... 24 elided

scala> createPerson("John -25")
AgeNegativeException: age: -25 should be > 0
  at .createPerson(:19)
  ... 24 elided

scala> createPerson("John 25.3")
java.lang.NumberFormatException: For input string: "25.3"
  at java.lang.NumberFormatException.forInputString(NumberFormatException.java:65)
  at java.lang.Integer.parseInt(Integer.java:580)
  at java.lang.Integer.parseInt(Integer.java:615)
  at scala.collection.immutable.StringLike.toInt(StringLike.scala:301)
  at scala.collection.immutable.StringLike.toInt$(StringLike.scala:301)
  at scala.collection.immutable.StringOps.toInt(StringOps.scala:29)
  at .createPerson(:17)
  ... 24 elided

Since the exceptions are not caught by any try...catch block, the Scala console shows a stack trace. The stack trace shows all the nested function calls that led to the point where the exception was thrown. In the last example, the val age = split(1).toInt line in createPerson called scala.collection.immutable.StringOps.toInt, which called scala.collection.immutable.StringLike.toInt$, and so on, until finally the java.lang.Integer.parseInt function threw the exception at line 580 in Integer.java.

In order to illustrate how exceptions bubble up the call stack, we are going to create a new averageAge function, which calculates the average age of a list of Person instances, using their string descriptions, as shown in the following code:

def averageAge(descriptions: Vector[String]): Double = {
  val total = descriptions.map(createPerson).map(_.age).sum
  total / descriptions.length
}

This function calls our previously implemented createPerson function, and therefore will throw any exception that is thrown by createPerson because there is no try...catch block in averageAge.

Now, we can implement another function on top that will parse an input containing several Person descriptions and return a summary in a string. It will print an error message in case the input cannot be parsed, as shown in the following code:

import scala.util.control.NonFatal
def personsSummary(personsInput: String): String = {
  val descriptions = personsInput.split("\n").toVector
  val avg = try {
    averageAge(descriptions)
  } catch {
    case e:AgeNegativeException =>
      println(s"one of the persons has a negative age: $e")
      0
    case NonFatal(e) =>
      println(s"something was wrong in the input: $e")
      0
  }
  s"${descriptions.length} persons with an average age of $avg"
}

In this function, we declare an avg value, which will get the return value of averageAge if no exception is thrown. If one of the descriptions contains a negative age, our catch block will print an error message, and avg will be assigned the value of 0. If another type of exception is thrown, and this exception is NonFatal, then we print another message and avg will also be assigned the value of 0. A fatal exception is an exception that cannot be recovered, such as OutOfMemoryException. You can look at the implementation of scala.util.control.NonFatal for more details.

The following code shows a few sample calls to personsSummary:

scala> personsSummary(
  """John 25
    |Sharleen 45""".stripMargin)
res1: String = 2 persons with an average age of 35.0

scala> personsSummary(
  """John 25
    |Sharleen45""".stripMargin)
something was wrong in the input: java.lang.ArrayIndexOutOfBoundsException: 1
res2: String = 2 persons with an average age of 0.0

scala> personsSummary(
 """John -25
 |Sharleen 45""".stripMargin)
one of the persons has a negative age: $line5.$read$$iw$$iw$AgeNegativeException: age should be > 0
res3: String = 2 persons with an average age of 0.0

As we can see, as soon as any of the descriptions cannot be parsed, an error is printed and the average age is set to 0.

A try...catch block can optionally be followed by a finally {} block. The code inside the finally block is always executed, even if an exception is not matched by any pattern in the catch block. The finally block is typically used to close any resource that is accessed inside the try block, such as a file or a network connection.

The following code shows how to use a URL to read a web page into a string:

import java.io.IOException
import java.net.URL
import scala.annotation.tailrec

val stream = new URL("https://www.packtpub.com/").openStream()
val htmlPage: String =
  try {
    @tailrec
    def loop(builder: StringBuilder): String = {
      val i = stream.read()
      if (i != -1)
        loop(builder.append(i.toChar))
      else
        builder.toString()
    }
    loop(StringBuilder.newBuilder)
  } catch {
    case e: IOException => s"cannot read URL: $e"
  }
  finally {
    stream.close()
  }

The finally block allows us to close InputStream, whether the reading of the page succeeded or not. This way, we will not leave a dangling open connection in case there is a network issue or a thread interruption.

Note that the preceding code is for illustrative purposes only. In a real project, you should use the following code format:

val htmlPage2 = scala.io.Source.fromURL("https://www.packtpub.com/").mkString

Now that you know how to use exceptions, we are going to define the concept of referential transparency and show how catching exceptions can break it. We will then explore better data structures that will let us manage errors without breaking referential transparency.

 We say that an expression is referentially transparent when it can be replaced by its value without changing the program's behavior, in any context. When an expression is a function call, it means that we can always substitute this function call with the return value of the function. A function that guarantees this in any context is called a pure function.

A pure function is like a mathematical function=E2=80=94the return value depends only on the arguments passed to the function. You do not have to consider anything else about the context in which it is called.

In the following code,  the pureSquare function is pure:

def pureSquare(x: Int): Int = x * x
val pureExpr = pureSquare(4) + pureSquare(3)
// pureExpr: Int = 25

val pureExpr2 = 16 + 9
// pureExpr2: Int = 25

The functions called pureSquare(4) and pureSquare(3) are referentially transparent=E2=80=94when we replace them with the return value of the function, the program's behavior does not change.

On the other hand, the following function is impure:

var globalState = 1
def impure(x: Int): Int = {
  globalState = globalState + x
  globalState
}
val impureExpr = impure(3)
// impureExpr: Int = 4
val impureExpr2 = 4

We cannot replace the call to impure(3) with its return value because the return value changes depending on the context. In fact, any function that has side effects is impure. A side effect can be any of the following constructs:

• Mutating a global variable
• Printing to the console
• Opening a network connection
• Reading/writing data to/from a file
• Reading/writing data to/from a database
• More generally, any interaction with the outside world

The following is another example of an impure function:

import scala.util.Random
def impureRand(): Int = Random.nextInt()
impureRand()
//res0: Int = -528134321
val impureExprRand = impureRand() + impureRand()
//impureExprRand: Int = 681209667
val impureExprRand2 = -528134321 + -528134321

You cannot substitute the result of impureRand() with its value because the value changes for every call. If you do so, the program's behavior changes. The call to impureRand() is not referentially transparent, and hence impureRand is impure. In fact, the random() function mutates a global variable to generate a new random number for every call. We can also say that this function is nondeterministic=E2=80=94we cannot predict its return value just by observing its arguments.

We can rewrite our impure function to make it pure, as shown in the following code:

def pureRand(seed: Int): Int = new Random(seed).nextInt()
pureRand(10)
//res1: Int = -1157793070
val pureExprRand = pureRand(10) + pureRand(10)
//pureExprRand: Int = 1979381156
val pureExprRand2 = -1157793070 + -1157793070
//pureExprRand2: Int = 1979381156

You can substitute the call to pureRand(seed) with its value; the function will always return the same value given the same seed. The call to pureRand is referentially transparent, and pureRand is a pure function.

The following is another example of an impure function:

def impurePrint(): Unit = println("Hello impure")
val impureExpr1: Unit = impurePrint()
val impureExpr2: Unit = ()

In the second example, the return value of impurePrint is of the Unit type. There is only one value of this type in the Scala SDK: the ()value. If we replace the call to impurePrint() with (), then the program's behavior changes=E2=80=94in the first case, something will be printed on the console, but not in the second case.

Referential transparency is a key concept in functional programming. If most of your program uses pure functions, then it becomes much easier to do the following:

• Understand what a program is doing: You know that the function's return value only depends on its arguments. You do not have to think about what the state of this or that variable is in this or that context. You just have to look at the arguments.
• Test your functions: I will restate this point=E2=80=94the function's return value only depends on its argument. Testing it is very simple; you can try different argument values and confirm that the return value is what you expect.
• Write multithreaded programs: Since a pure function's behavior does not depend on a global state, you can execute it in parallel on multiple threads or even on different machines. The return values will not change. As our CPUs are built with more and more cores these days, this will help you write faster programs.

However, it is not possible to only have pure functions in a program because, in essence, a program must interact with the outside world. It has to print something, read some user input, or save some state in a database. In functional programming, the best practice is to use pure functions in the majority of the code base and to push the impure side-effecting functions to the boundaries of the program.

For instance, in Chapter 2, Developing a Retirement Calculator, we implemented a retirement calculator that mostly uses pure functions. One side-effecting function was the println call in the SimulatePlanApp object, which was at the boundaries of the program. There were other side effects in EquityData.fromFile and InflationData.fromFile; these functions are for reading files. However, the resource files can never change for the duration of the program. For a given filename, we would always get the same file content, and we could substitute the return value of fromFile in all calls without changing the program's behavior. In this case, the side effect of reading a file is not observable, and we can consider theses file-reading functions as being pure. Another side-effecting function was strMain because it could throw exceptions. In the rest of this chapter, we will see why throwing exceptions break referential transparency, and we will learn how to replace it with better functional programming structures.

Note that a pure function can use mutable variables or side effects inside the body of the function. As long as these effects are not observable by the caller, we consider the function pure. In the Scala SDK, many pure functions are implemented using mutable variables to improve performance. Look, for the instance, at the following implementation of TraversableOnce.foldLeft:

def foldLeft[B](z: B)(op: (B, A) => B): B = {
  var result = z
  this foreach (x => result = op(result, x))
  result
}

This might not seem obvious, but when a function throws an exception, it breaks referential transparency. In this section, I am going to show you why. First, create a new Scala worksheet and type the following definitions:

case class Rectangle(width: Double, height: Double)

def area(r: Rectangle): Double =
  if (r.width > 5 || r.height > 5)
    throw new IllegalArgumentException("too big")
  else
    r.width * r.height

Then, we will call area with the following arguments:

val area1 = area(3, 2)
val area2 = area(4, 2)

val total = try {
  area1 + area2
} catch {
  case e: IllegalArgumentException => 0
}

We get total: Double = 14.0. In the preceding code, the area1 and area2 expressions are referentially transparent. We can indeed substitute them with their value without changing the program's behavior. In IntelliJ, select the area1 variable inside the try block and hit Ctrl + Alt + N (inline variable), as shown in the following code. Do the same for area2:

val total = try {
  area(3, 2) + area(4, 2)
} catch {
  case e: IllegalArgumentException => 0
}

The total is the same as before. The program's behavior did not change, hence area1 and area2 are referentially transparent. However, let's see what happens if we define area1 in the following way:

val area1 = area(6, 2)
val area2 = area(4, 2)

val total = try {
  area1 + area2
} catch {
  case e: IllegalArgumentException => 0
}

In this case, we get java.lang.IllegalArgumentException: too big, because our area(...) function throws an exception when the width is greater than five. Now let's see what happens if we inline area1 and area2 as before, as shown in the following code:

val total = try {
  area(6, 2) + area(4, 2)
} catch {
  case e: IllegalArgumentException => 0
}

In this case, we get total: Double = 0.0. The program's behavior changed when substituting area1 with its value, hence area1 is not referentially transparent.

We demonstrated that exception handling breaks referential transparency, and hence functions that throw exceptions are impure. It makes a program more difficult to understand because you have to take into account where a variable is defined to understand how the program will behave. The behavior will change depending on whether a variable is defined inside or outside a try block. This might not seem to be a big deal in a trivial example, but when there are multiple chained function calls with try blocks along the line, matching different types of exceptions, it can become daunting.

Another disadvantage when you use exceptions is that the signature of the function does not indicate that it can throw an exception. When you call a function that can throw exceptions, you have to look at its implementation to figure out what type of exception it can throw, and under what circumstances. If the function calls other functions, it compounds the problem. You can accommodate this by adding comments or an @throws annotation to indicate what exception types can be thrown, but these can become outdated when the code is refactored. When we call a function, we should only have to consider its signature. A signature is a bit like a contract=E2=80=94given these arguments, I will return you a result. If you have to look at the implementation to know what exceptions are thrown, it means that the contract is not completed: some information is hidden.

We now know how to throw and catch exceptions, and why we should use them with caution. The best practice is to do the following:

• Catch recoverable exceptions as early as possible, and indicate the possibility of failure with a specific return type.
• Not catch exceptions that cannot be recovered, such as disk full, out of memory, or some other catastrophic failure. This will make your program crash whenever such exceptions happen, and you should then have a manual or automatic recovery process outside the program.

In the rest of this chapter, I will show you how to use the Option, Either, and Validated classes to model the possibility of a failure.

The Scala Option type is an algebraic data type (ADT) that represents an optional value. It can also be viewed as List that can contain either one or no elements. It is a safe replacement for a null reference that you might have used if you have programmed in Java, C++, or C#.

The following is a simplified definition of the Option ADT:

sealed trait Option[+A]
case class Some[A](value: A) extends Option[A]
case object None extends Option[Nothing]

The Scala SDK provides a more refined implementation; the preceding definition is just for illustrative purpose. This definition implies that Option can be either of the following two types:

• Some(value), which represents an optional value where the value is present
• None, which represents an optional value where the value is not present.

The following are some examples of the usage of the different types of Option that you can paste in a Scala worksheet:

val opt0: Option[Int] = None
// opt0: Option[Int] = None

val opt1: Option[Int] = Some(1)
// opt1: Option[Int] = Some(1)

val list0 = List.empty[String]
list0.headOption
// res0: Option[String] = None
list0.lastOption
// res1: Option[String] = None

val list3 = List("Hello", "World")
list3.headOption
// res2: Option[String] = Some(Hello)
list3.lastOption
// res3: Option[String] = Some(World)

Explanation of the preceding code is as follows:

• The first two examples show how we can define an Option type that can optionally contain Int.
• The following examples use the headOption and lastOption methods in List to show that many safe functions of the SDK return Option. If List is empty, these functions always return None. Note that the SDK also provides unsafe equivalent head and last methods. The unsafe methods throw an exception if we call them with an empty List, which might crash our program if we do not catch the exception.

Since Option is an ADT, we can use pattern matching to test whether Option is None or Some, as shown in the following code:

def personDescription(name: String, db: Map[String, Int]): String =
  db.get(name) match {
    case Some(age) => s"$name is $age years old"
    case None => s"$name is not present in db"
  }

val db = Map("John" -> 25, "Rob" -> 40)
personDescription("John", db)
// res4: String = John is 25 years old
personDescription("Michael", db)
// res5: String = Michael is not present in db

The get(key)method in Map returns Option, containing the value associated with the key. If the key does not exist in Map, it returns None. When you start using Option, pattern matching is the most natural way of triggering different behaviors depending on the content of Option.

Another way is to use map and getOrElse, as shown in the following code:

def personDesc(name: String, db: Map[String, Int]): String = {
  val optString: Option[String] = db.get(name).map(age => s"$name is 
  $age years old")
  optString.getOrElse(s"$name is not present in db")
}

We saw earlier how to transform the elements of a vector using map. This works exactly the same for Option=E2=80=94we pass an anonymous function that will be called with the option's value if Option is not empty. Since our anonymous function returns a string, we obtain Option[String]. We then call getOrElse, which provides a value in case Option is None. The getOrElse phrase is a good way to safely extract the content of Option.

Using the same db: Map[String, Int] phrase, containing the ages of different people, the following code is a naive implementation of a function that returns the average age of two people:

def averageAgeA(name1: String, name2: String, db: Map[String, Int]): Option[Double] = {
  val optOptAvg: Option[Option[Double]] =
    db.get(name1).map(age1 =>
      db.get(name2).map(age2 =>
        (age1 + age2).toDouble / 2))
  optOptAvg.flatten
}
val db = Map("John" -> 25, "Rob" -> 40)
averageAge("John", "Rob", db)
// res6: Option[Double] = Some(32.5)
averageAge("John", "Michael", db)
// res7: Option[Double] = None

The function returns Option[Double]. If name1 or name2 cannot be found in the db map, averageAge returns None. If both names are found, it returns Some(value). The implementation uses map to transform the value contained in the option. We end up with a nested Option[Option[Double]], but our function must return Option[Double]. Fortunately, we can use flatten to remove one level of nesting.

We managed to implement averageAge, but we can improve it using flatMap, as shown in the following code:

def averageAgeB(name1: String, name2: String, db: Map[String, Int]): Option[Double] =
  db.get(name1).flatMap(age1 =>
    db.get(name2).map(age2 =>
      (age1 + age2).toDouble / 2))

As its name suggests, flatMap is equivalent to composing flatten and map. In our function, we replaced map(...).flatten with flatMap(...).

So far, so good, but what if we want to get the average age of three or four people? We would have to nest several instances of flatMap, which would not be very pretty or readable. Fortunately, Scala provides a syntactic sugar that allows us to simplify our function further, called the for comprehension, as shown in the following code:

def averageAgeC(name1: String, name2: String, db: Map[String, Int]): Option[Double] =
  for {
    age1 <- db.get(name1)
    age2 <- db.get(name2)
  } yield (age1 + age2).toDouble / 2

When you compile a for comprehension, such as for { ... } yield { ... }, the Scala compiler transforms it into a composition of flatMap/map operations. Here is how it works:

• Inside the for block, there can be one or many expressions phrased as variable <- context, which is called a generator. The left side of the arrow is the name of a variable that is bound to the content of the context on the right of the arrow.
• Every generator except the last one is transformed into a flatMap expression.
• The last generator is transformed into a map expression.
• All context expressions (the right side of the arrow) must have the same context type.

In the preceding example, we used Option for the context type, but for yield can also be used with any class that has a flatMap and map operation. For instance, we can use for..yield with Vector to run nested loops, as shown in the following code:

for {
  i <- Vector("one", "two")
  j <- Vector(1, 2, 3)
} yield (i, j)
// res8: scala.collection.immutable.Vector[(String, Int)] = 
// Vector((one,1), (one,2), (one,3), (two,1), (two,2), (two,3))

Now that we know what Option can do for us, we are going to refactor one of the functions of the retirement calculator that we developed in Chapter 2, Developing a Retirement Calculator, to improve the handling of some edge-case scenarios. If you have not done it yet, please follow the instructions at the beginning of the Chapter 2, Developing a Retirement Calculator, to set up the project.

In RetCalc.scala, we are going to change the return type of nbMonthsSaving. In Chapter 2, Developing a Retirement Calculator, we returned Int.MaxValue if netIncome <= currentExpense to avoid looping infinitely. This was not very robust, as this infinite result could then be used in another computation, which would lead to bogus results. It would be better to return Option[Int] to indicate that the function might not be computable and let the caller decide what to do. We would return None if it was not computable or Some(returnValue) if it was computable.

The following code is the new implementation for nbMonthsSaving, with the changed portions highlighted in bold:

def nbOfMonthsSaving(params: RetCalcParams, 
                     returns: Returns): Option[Int] = {
  import params._
  @tailrec
  def loop(months: Int): Int = {
    val (capitalAtRetirement, capitalAfterDeath) = 
      simulatePlan(returns, params, months)

    if (capitalAfterDeath > 0.0)
      months
    else
      loop(months + 1)
  }

  if (netIncome > currentExpenses)
    Some(loop(0))
  else
    None
}

Now try to compile the project. This change breaks many parts of our project, but the Scala compiler is a terrific assistant. It will help us identify the portions of the code we need to change to make our code more robust.

The first error is in RetCalcSpec.scala, as shown in the following code:

Error:(65, 14) types Option[Int] and Int do not adhere to the type constraint selected for the === and !== operators; the missing implicit parameter is of type org.scalactic.CanEqual[Option[Int],Int]
      actual should ===(expected)

This error means that the types in the actual should =3D=3D=3D (expected) expression do not match: actual is of the Option[Int]0 type, whereas expected is of the Int type. We need to change the assertion, as follows:

actual should ===(Some(expected))

You can apply the same fix for the second unit test. For the last unit test, we want to assert that None is returned instead of Int.MaxValue, as shown in the following code:

"not loop forever if I enter bad parameters" in {
  val actual = RetCalc.nbOfMonthsSaving(params.copy(netIncome = 1000), FixedReturns(0.04))
  actual should ===(None)
}

You can now compile and run the test. It should pass.

You are now able to model an optional value safely. However, sometimes it is not always obvious to know what None actually means. Why did this function return None? Was it because the arguments that were passed were wrong? Which argument was wrong? And what value would be correct? It would indeed be nice to have some explanation that comes along with the None in order to understand why there was no value. In the next section, we are going to use the Either type for this purpose.

The Either type is an ADT that represents a value of either a Left type or a Right type. A simplified definition of Either would be the following:

sealed trait Either[A, B]
case class Left[A, B](value: A) extends Either[A, B]
case class Right[A, B](value: B) extends Either[A, B]

When you instantiate a Right type, you need to provide a value of a B type, and when you instantiate a Left type, you need to provide a value of an A type. Therefore, Either[A, B] can either hold a value of type A or a value of type B.

The following code shows an example of such a usage that you can type in a new Scala worksheet:

def divide(x: Double, y: Double): Either[String, Double] =
  if (y == 0)
    Left(s"$x cannot be divided by zero")
  else
    Right(x / y)

divide(6, 3)
// res0: Either[String,Double] = Right(2.0)
divide(6, 0)
// res1: Either[String,Double] = Left(6.0 cannot be divided by zero) 

The divide function returns either a string or a double:

• If the function cannot compute a value, it returns an error String wrapped in a Left type
• If the function can compute a correct value, it returns the Double value wrapped in a Right type

By convention, we use Right to represent the correct or right value, and we use Left to represent an error.

Since Either is an ADT, we can use pattern matching to decide what to do when we get a Left or Right type.

The following is a modified version of the personDescription function that we showed earlier in the Using Option section:

def getPersonAge(name: String, db: Map[String, Int]): Either[String, Int] =
  db.get(name).toRight(s"$name is not present in db")

def personDescription(name: String, db: Map[String, Int]): String =
  getPersonAge(name, db) match {
    case Right(age) => s"$name is $age years old"
    case Left(error) => error
  }

val db = Map("John" -> 25, "Rob" -> 40)
personDescription("John", db)
// res4: String = John is 25 years old
personDescription("Michael", db)
// res5: String = Michael is not present in db

The first getPersonAge function produces Right(age) if the name argument is present in db. If name is not present in db, it returns an error message wrapped in a Left type. For this purpose, we use the Option.toRight method. I encourage you to have a look at the documentation and implementation of this method.

The implementation of personDescription is straightforward=E2=80=94we pattern match using the result of getPersonAge and return an appropriate String depending on whether the result is a Left or Right type.

As with Option, we can also use map and flatMap to combine several instances of Either, as shown in the following code:

def averageAge(name1: String, name2: String, db: Map[String, Int]): Either[String, Double] =
  getPersonAge(name1, db).flatMap(age1 =>
    getPersonAge(name2, db).map(age2 =>
      (age1 + age2).toDouble / 2))

averageAge("John", "Rob", db)
// res4: Either[String,Double] = Right(32.5)
averageAge("John", "Michael", db)
// res5: Either[String,Double] = Left(Michael is not present in db)

Note how the body of the function is almost the same as Option. This is because Either is right biased, meaning that map and flatMap transform the right side of Either.

If you want to transform the Left side of Either, you need to call the Either.left method, as shown in the following code:

getPersonAge("bob", db).left.map(err => s"The error was: $err")
// res6: scala.util.Either[String,Int] = Left(The error was: bob is not present in db)

Since Either implements map and flatMap, we can refactor averageAge to use a for comprehension, as shown in the following code:

def averageAge2(name1: String, name2: String, db: Map[String, Int]): Either[String, Double] =
  for {
    age1 <- getPersonAge(name1, db)
    age2 <- getPersonAge(name2, db)
  } yield (age1 + age2).toDouble / 2

Again, the code looks the same as it did with Option.

Now that we have a good understanding of how to manipulate Either, we are going to refactor our retirement calculator to take advantage of it.

In the previous section, we changed the return type of nbOfMonthsSavings to return Option[Int]. The function returned None if the expenses arguments were greater than income. We are now going to change it to return an error message wrapped in Left.

We could use a simple string for our error message, but the best practice when using Either is to create an ADT for all of the possible error messages. Create a new Scala class in src/main/scala/retcalc called RetCalcError, as shown in the following code:

package retcalc

sealed abstract class RetCalcError(val message: String)

object RetCalcError {
  case class MoreExpensesThanIncome(income: Double, expenses: Double) 
  extends RetCalcError(
    s"Expenses: $expenses >=  $income. You will never be able to save 
    enough to retire !")
}

We define a RetCalcError trait that has only one message method. This method will produce the error message whenever we need to return it to the user. Inside the RetCalcError object, we define one case class per type of error message. We will then change the functions that need to return an error to return Either[RetCalcError, A].

This pattern has many advantages over just using String, as shown in the following list:

• All of the error messages are located in one place. It allows you to immediately know what are all the possible error messages that can be returned to the user. You could also add different translations if your application uses multiple languages.
• Since RetCalcError is an ADT, you can use pattern matching to recover from a specific error and take action.
• It simplifies testing. You can test whether a function returns a specific type of error without having to assert on the error message itself. This way, you can change your error messages without having to change any test.

Now we can refactor our RetCalc.nbOfMonthsSavings function to return Either[RetCalcError, Int], as shown in the following code:

def nbOfMonthsSaving(params: RetCalcParams, 
                     returns: Returns): Either[RetCalcError, Int] = {
  import params._
  @tailrec
  def loop(months: Int): Int = {
    val (capitalAtRetirement, capitalAfterDeath) = 
      simulatePlan(returns, params, months)
    if (capitalAfterDeath > 0.0)
      months
    else
      loop(months + 1)
  }

  if (netIncome > currentExpenses)
    Right(loop(0))
  else
    Left(MoreExpensesThanIncome(netIncome, currentExpenses))
}

We also have to change the corresponding unit tests. ScalaTest provides convenient extensions to perform assertions on the Either type. To bring them in scope, extend EitherValues in RetCalcSpec.scala, as shown in the following code:

class RetCalcSpec extends WordSpec with Matchers with TypeCheckedTripleEquals 
  with EitherValues {

If you have a myEither variable of the Either[A, B] type in your test, then EitherValues will let us use the following methods:

• myEither.left.value returns the left value of type A or fails the test if myEither is Right
• myEither.right.value returns the right value of type B or fails the test if myEither is Left

We can now change our unit tests on nbOfMonthsSaving as follows:

"RetCalc.nbOfMonthsSaving" should {
  "calculate how long I need to save before I can retire" in {
    val actual = RetCalc.nbOfMonthsSaving(params, 
    FixedReturns(0.04)).right.value
    val expected = 23 * 12 + 1
    actual should ===(expected)
  }

  "not crash if the resulting nbOfMonths is very high" in {
    val actual = RetCalc.nbOfMonthsSaving(
      params = RetCalcParams(
        nbOfMonthsInRetirement = 40 * 12,
        netIncome = 3000, currentExpenses = 2999, initialCapital = 0),
      returns = FixedReturns(0.01)).right.value
    val expected = 8280
    actual should ===(expected)
  }

  "not loop forever if I enter bad parameters" in {
    val actual = RetCalc.nbOfMonthsSaving(
      params.copy(netIncome = 1000), FixedReturns(0.04)).left.value
    actual should ===(RetCalcError.MoreExpensesThanIncome(1000, 2000))
  }
}

Run the unit test. It should pass.

In Chapter 2, Developing a Retirement Calculator, we implemented a Returns.monthlyRate(returns: Returns, month: Int): Double function that returned the monthly return rate for a given month. When we called it with a month exceeding the size of an instance of VariableReturns, we rolled over to the first month using a modulo operation.

This was not completely satisfying, as it could compute unrealistic simulations. Say that your VariableReturns instance contains data for 1950 to 2017. When you ask the monthly returns for 2018, monthlyRate would give you the returns that we had in 1950. The economic outlook of the fifties was very different compared to the current one, and it is unlikely that the returns in 2018 will mirror those in 1950.

Therefore, we are going to change monthlyRate to return an error if the month argument is outside the bounds of VariableReturn. First, open RetCalcError.scala and add the following error type:

case class ReturnMonthOutOfBounds(month: Int, maximum: Int) extends RetCalcError(
  s"Cannot get the return for month $month. Accepted range: 0 to $maximum")

Next, we are going to change the unit tests to specify the function that we expect it to return. Open ReturnsSpec.scala and change the tests as follows:

"Returns.monthlyReturn" should {
  "return a fixed rate for a FixedReturn" in {
    Returns.monthlyRate(FixedReturns(0.04), 0).right.value should ===
    (0.04 / 12)
    Returns.monthlyRate(FixedReturns(0.04), 10).right.value should ===
    (0.04 / 12)
  }

  val variableReturns = VariableReturns(
    Vector(VariableReturn("2000.01", 0.1), VariableReturn("2000.02", 
    0.2)))
  "return the nth rate for VariableReturn" in {
    Returns.monthlyRate(variableReturns, 0).right.value should ===(0.1)
    Returns.monthlyRate(variableReturns, 1).right.value should ===(0.2)
  }

  "return None if n > length" in {
    Returns.monthlyRate(variableReturns, 2).left.value should ===(
      RetCalcError.ReturnMonthOutOfBounds(2, 1))
    Returns.monthlyRate(variableReturns, 3).left.value should ===(
      RetCalcError.ReturnMonthOutOfBounds(3, 1))
  }

  "return the n+offset th rate for OffsetReturn" in {
    val returns = OffsetReturns(variableReturns, 1)
    Returns.monthlyRate(returns, 0).right.value should ===(0.2)
  }
}

Then, open Returns.scala and change monthlyRate As follows:

def monthlyRate(returns: Returns, month: Int): Either[RetCalcError, Double] = returns match {
  case FixedReturns(r) => Right(r / 12)

  case VariableReturns(rs) =>
    if (rs.isDefinedAt(month))
      Right(rs(month).monthlyRate)
    else
      Left(RetCalcError.ReturnMonthOutOfBounds(month, rs.size - 1))

  case OffsetReturns(rs, offset) => monthlyRate(rs, month + offset)
}

Try to compile the project now. Since monthlyRate is called by other functions, we will get some compilation errors, which is actually a good thing. We just have to fix the compilation errors to make our code deal with the possibility of an error. Every fix requires some thinking about what to do with that possibility.

On the other hand, if we had thrown an exception instead of returning Either, everything would have compiled, but the program would have crashed whenever the month was out of bounds. It would have been more difficult to achieve the desired behavior because the compiler would not have helped us.

The first compilation error is in RetCalc.scala in futureCapital, as shown in the following code:

Error:(55, 26) overloaded method value + with alternatives:
(...)
 cannot be applied to (Either[retcalc.RetCalcError,Double])
        accumulated * (1 + Returns.monthlyRate(returns, month)) + 
        monthlySavings

This means that we cannot call the + method on Either[RetCalcError, Double]. If monthlyRate returns Left, we cannot calculate the accumulated capital. The best course of action would be to stop here and return the error. For this, we need to change the return type of futureCapital to Either[RetCalcError, Double] as well.

The following is the corrected version of the function:

def futureCapital(returns: Returns, nbOfMonths: Int, netIncome: Int, currentExpenses: Int,
                  initialCapital: Double): Either[RetCalcError, Double] = {
  val monthlySavings = netIncome - currentExpenses
  (0 until nbOfMonths).foldLeft[Either[RetCalcError, Double]]
  (Right(initialCapital)) {
    case (accumulated, month) =>
      for {
        acc <- accumulated
        monthlyRate <- Returns.monthlyRate(returns, month)
      } yield acc * (1 + monthlyRate) + monthlySavings
  }
}

In the second line, we changed the initial element passed to foldLeft. We are now accumulating Either[RetCalcError, Double]. Note that we have to explicitly specify the type parameter for foldLeft. In the previous version of the function, when we were using Double, that type was inferred automatically.

If we do not specify the type parameter, the compiler will infer it to be of the type of the initial element. In our case, Right(initialCapital) is of the Right[Nothing, Double] type, which is a subclass of Either[RetCalcError, Double]. The problem is that, inside the anonymous function, we return Either[RetCalcError, Double], not Right[Nothing, Double]. The compiler would complain that the types do not match.

Inside the anonymous function passed to foldLeft, we use a for comprehension to do the following:

• Return the accumulated result in Right if both acc and monthlyRate are Right
• Return Left if acc or monthlyRate is Left

Note that our implementation does not stop as soon as monthlyRate returns Left, which is a bit inefficient. There is no point in iterating through the other months when we get an error because this function should always return the first error it encounters. In Chapter 4, Advanced Features, we will see how we can use lazy evaluation with foldr to stop the iteration early.

Compile the project again. Now we need to fix a compilation error in simulatePlan.

Since simulatePlan calls futureCapital, we need to change its implementation to take into account the new return type, as shown in the following code:

def simulatePlan(returns: Returns, params: RetCalcParams, nbOfMonthsSavings: Int,
                 monthOffset: Int = 0): Either[RetCalcError, (Double, 
Double)] = {
  import params._

  for {
    capitalAtRetirement <- futureCapital(
      returns = OffsetReturns(returns, monthOffset),
      nbOfMonths = nbOfMonthsSavings, netIncome = netIncome, 
      currentExpenses = currentExpenses,
      initialCapital = initialCapital)

    capitalAfterDeath <- futureCapital(
      returns = OffsetReturns(returns, monthOffset + 
      nbOfMonthsSavings),
      nbOfMonths = nbOfMonthsInRetirement,
      netIncome = 0, currentExpenses = currentExpenses,
      initialCapital = capitalAtRetirement)
  } yield (capitalAtRetirement, capitalAfterDeath)
}